@maggioli-design-system/magma 2.11.0 → 2.13.0

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 (1661) hide show
  1. package/AGENTS.md +2 -2
  2. package/CHANGELOG.md +110 -0
  3. package/README.md +15 -11
  4. package/agents/assets.md +7 -6
  5. package/agents/color.md +8 -4
  6. package/agents/components.md +3 -2
  7. package/agents/conventions.md +11 -1
  8. package/agents/install.md +10 -3
  9. package/agents/mcp.md +5 -5
  10. package/agents/patterns/actions.md +11 -9
  11. package/agents/patterns/app-shell.md +70 -22
  12. package/agents/patterns/density.md +4 -3
  13. package/agents/patterns/empty-state.md +5 -7
  14. package/agents/patterns/previews/actions/banner.dark.webp +0 -0
  15. package/agents/patterns/previews/actions/banner.light.webp +0 -0
  16. package/agents/patterns/previews/actions/confirm.dark.webp +0 -0
  17. package/agents/patterns/previews/actions/confirm.light.webp +0 -0
  18. package/agents/patterns/previews/actions/danger-zone.dark.webp +0 -0
  19. package/agents/patterns/previews/actions/danger-zone.light.webp +0 -0
  20. package/agents/patterns/previews/actions/dismiss-message.light.webp +0 -0
  21. package/agents/patterns/previews/actions/dismiss.dark.webp +0 -0
  22. package/agents/patterns/previews/actions/dismiss.light.webp +0 -0
  23. package/agents/patterns/previews/actions/part-primary.light.webp +0 -0
  24. package/agents/patterns/previews/actions/stacked.light.webp +0 -0
  25. package/agents/patterns/previews/app-shell/back-office.dark.webp +0 -0
  26. package/agents/patterns/previews/app-shell/back-office.html +2 -2
  27. package/agents/patterns/previews/app-shell/back-office.light.webp +0 -0
  28. package/agents/patterns/previews/app-shell/many-sections.dark.webp +0 -0
  29. package/agents/patterns/previews/app-shell/many-sections.html +1 -1
  30. package/agents/patterns/previews/app-shell/many-sections.light.webp +0 -0
  31. package/agents/patterns/previews/app-shell/public-service.dark.webp +0 -0
  32. package/agents/patterns/previews/app-shell/public-service.html +2 -2
  33. package/agents/patterns/previews/app-shell/public-service.light.webp +0 -0
  34. package/agents/patterns/previews/app-shell/section-menus.dark.webp +0 -0
  35. package/agents/patterns/previews/app-shell/section-menus.html +68 -0
  36. package/agents/patterns/previews/app-shell/section-menus.light.webp +0 -0
  37. package/agents/patterns/previews/confirm-action/ask-before-sending.dark.webp +0 -0
  38. package/agents/patterns/previews/confirm-action/ask-before-sending.light.webp +0 -0
  39. package/agents/patterns/previews/confirm-action/ask-first-many.dark.webp +0 -0
  40. package/agents/patterns/previews/confirm-action/ask-first-many.light.webp +0 -0
  41. package/agents/patterns/previews/confirm-action/ask-first.dark.webp +0 -0
  42. package/agents/patterns/previews/confirm-action/ask-first.light.webp +0 -0
  43. package/agents/patterns/previews/confirm-action/make-reversible.dark.webp +0 -0
  44. package/agents/patterns/previews/confirm-action/make-reversible.light.webp +0 -0
  45. package/agents/patterns/previews/confirm-action/send-as-shown.dark.webp +0 -0
  46. package/agents/patterns/previews/confirm-action/send-as-shown.light.webp +0 -0
  47. package/agents/patterns/previews/empty-state/add-the-first.dark.webp +0 -0
  48. package/agents/patterns/previews/empty-state/add-the-first.html +5 -7
  49. package/agents/patterns/previews/empty-state/add-the-first.light.webp +0 -0
  50. package/agents/patterns/previews/empty-state/all-done.dark.webp +0 -0
  51. package/agents/patterns/previews/empty-state/all-done.html +5 -7
  52. package/agents/patterns/previews/empty-state/all-done.light.webp +0 -0
  53. package/agents/patterns/previews/empty-state/clear-filters.dark.webp +0 -0
  54. package/agents/patterns/previews/empty-state/clear-filters.html +4 -6
  55. package/agents/patterns/previews/empty-state/clear-filters.light.webp +0 -0
  56. package/agents/patterns/previews/empty-state/filled-by-others.dark.webp +0 -0
  57. package/agents/patterns/previews/empty-state/filled-by-others.html +5 -7
  58. package/agents/patterns/previews/empty-state/filled-by-others.light.webp +0 -0
  59. package/agents/patterns/previews/empty-state/not-found.dark.webp +0 -0
  60. package/agents/patterns/previews/empty-state/not-found.html +7 -9
  61. package/agents/patterns/previews/empty-state/not-found.light.webp +0 -0
  62. package/agents/patterns/previews/error-recovery/changed-meanwhile.dark.webp +0 -0
  63. package/agents/patterns/previews/error-recovery/changed-meanwhile.light.webp +0 -0
  64. package/agents/patterns/previews/error-recovery/check-or-repeat.light.webp +0 -0
  65. package/agents/patterns/previews/error-recovery/content-another-way.light.webp +0 -0
  66. package/agents/patterns/previews/error-recovery/partial.dark.webp +0 -0
  67. package/agents/patterns/previews/error-recovery/partial.light.webp +0 -0
  68. package/agents/patterns/previews/error-recovery/retry-action.light.webp +0 -0
  69. package/agents/patterns/previews/error-recovery/retry-content.dark.webp +0 -0
  70. package/agents/patterns/previews/error-recovery/sign-in-again.dark.webp +0 -0
  71. package/agents/patterns/previews/error-recovery/sign-in-again.light.webp +0 -0
  72. package/agents/patterns/previews/item-list/documents-of-a-request.dark.webp +0 -0
  73. package/agents/patterns/previews/item-list/documents-of-a-request.light.webp +0 -0
  74. package/agents/patterns/previews/item-list/queue-of-a-desk.dark.webp +0 -0
  75. package/agents/patterns/previews/item-list/queue-of-a-desk.html +1 -1
  76. package/agents/patterns/previews/item-list/queue-of-a-desk.light.webp +0 -0
  77. package/agents/patterns/previews/item-list/requests-of-an-office.dark.webp +0 -0
  78. package/agents/patterns/previews/item-list/requests-of-an-office.light.webp +0 -0
  79. package/agents/patterns/previews/item-list/requests-to-assign.dark.webp +0 -0
  80. package/agents/patterns/previews/item-list/requests-to-assign.html +3 -12
  81. package/agents/patterns/previews/item-list/requests-to-assign.light.webp +0 -0
  82. package/agents/patterns/previews/labels-and-values/payment-before-paying.dark.webp +0 -0
  83. package/agents/patterns/previews/labels-and-values/what-is-sent.dark.webp +0 -0
  84. package/agents/patterns/previews/labels-and-values/what-is-sent.light.webp +0 -0
  85. package/agents/patterns/previews/list-with-filters/act-on-many.dark.webp +0 -0
  86. package/agents/patterns/previews/list-with-filters/act-on-many.html +4 -11
  87. package/agents/patterns/previews/list-with-filters/act-on-many.light.webp +0 -0
  88. package/agents/patterns/previews/list-with-filters/find-and-open.dark.webp +0 -0
  89. package/agents/patterns/previews/list-with-filters/find-and-open.html +2 -2
  90. package/agents/patterns/previews/list-with-filters/find-and-open.light.webp +0 -0
  91. package/agents/patterns/previews/list-with-filters/show-new-items.dark.webp +0 -0
  92. package/agents/patterns/previews/list-with-filters/show-new-items.html +3 -3
  93. package/agents/patterns/previews/list-with-filters/show-new-items.light.webp +0 -0
  94. package/agents/patterns/previews/loading/await-and-say.dark.webp +0 -0
  95. package/agents/patterns/previews/loading/await-and-say.html +2 -5
  96. package/agents/patterns/previews/loading/first-load.dark.webp +0 -0
  97. package/agents/patterns/previews/loading/first-load.light.webp +0 -0
  98. package/agents/patterns/previews/loading/keep-while-reloading.light.webp +0 -0
  99. package/agents/patterns/previews/loading/long-load-measured.dark.webp +0 -0
  100. package/agents/patterns/previews/loading/long-load-measured.light.webp +0 -0
  101. package/agents/patterns/previews/loading/long-load.dark.webp +0 -0
  102. package/agents/patterns/previews/loading/long-load.light.webp +0 -0
  103. package/agents/patterns/previews/loading/progress-in-place.light.webp +0 -0
  104. package/agents/patterns/previews/message-placement/action-done-elsewhere.dark.webp +0 -0
  105. package/agents/patterns/previews/message-placement/action-done-elsewhere.light.webp +0 -0
  106. package/agents/patterns/previews/message-placement/action-failed-elsewhere.dark.webp +0 -0
  107. package/agents/patterns/previews/message-placement/action-failed-elsewhere.light.webp +0 -0
  108. package/agents/patterns/previews/message-placement/action-failed-in-place.dark.webp +0 -0
  109. package/agents/patterns/previews/message-placement/action-failed-in-place.light.webp +0 -0
  110. package/agents/patterns/previews/message-placement/action-partial-in-place.dark.webp +0 -0
  111. package/agents/patterns/previews/message-placement/action-partial-in-place.light.webp +0 -0
  112. package/agents/patterns/previews/message-placement/app-deadline.dark.webp +0 -0
  113. package/agents/patterns/previews/message-placement/app-deadline.light.webp +0 -0
  114. package/agents/patterns/previews/message-placement/app-failed.dark.webp +0 -0
  115. package/agents/patterns/previews/message-placement/app-failed.html +2 -2
  116. package/agents/patterns/previews/message-placement/app-failed.light.webp +0 -0
  117. package/agents/patterns/previews/message-placement/decision.dark.webp +0 -0
  118. package/agents/patterns/previews/message-placement/decision.light.webp +0 -0
  119. package/agents/patterns/previews/message-placement/field-error.dark.webp +0 -0
  120. package/agents/patterns/previews/message-placement/field-error.light.webp +0 -0
  121. package/agents/patterns/previews/message-placement/field-hint.light.webp +0 -0
  122. package/agents/patterns/previews/message-placement/field-valid.dark.webp +0 -0
  123. package/agents/patterns/previews/message-placement/field-valid.light.webp +0 -0
  124. package/agents/patterns/previews/message-placement/region-failed.dark.webp +0 -0
  125. package/agents/patterns/previews/message-placement/region-info.dark.webp +0 -0
  126. package/agents/patterns/previews/message-placement/region-info.light.webp +0 -0
  127. package/agents/patterns/previews/page-header/contact-being-edited.dark.webp +0 -0
  128. package/agents/patterns/previews/page-header/contact-being-edited.light.webp +0 -0
  129. package/agents/patterns/previews/page-header/members-of-a-group.light.webp +0 -0
  130. package/agents/patterns/previews/page-header/request-from-the-list.dark.webp +0 -0
  131. package/agents/patterns/previews/record-detail/ask-for-words.dark.webp +0 -0
  132. package/agents/patterns/previews/record-detail/ask-for-words.html +2 -2
  133. package/agents/patterns/previews/record-detail/ask-for-words.light.webp +0 -0
  134. package/agents/patterns/previews/record-detail/edit-data.dark.webp +0 -0
  135. package/agents/patterns/previews/record-detail/edit-data.html +2 -2
  136. package/agents/patterns/previews/record-detail/edit-data.light.webp +0 -0
  137. package/agents/patterns/previews/record-detail/read-the-data.dark.webp +0 -0
  138. package/agents/patterns/previews/record-detail/read-the-data.html +2 -2
  139. package/agents/patterns/previews/record-detail/read-the-data.light.webp +0 -0
  140. package/agents/patterns/previews/record-detail/record-changed.dark.webp +0 -0
  141. package/agents/patterns/previews/record-detail/record-changed.html +2 -2
  142. package/agents/patterns/previews/record-detail/record-changed.light.webp +0 -0
  143. package/agents/patterns/previews/record-detail/run-at-once.dark.webp +0 -0
  144. package/agents/patterns/previews/record-detail/run-at-once.html +2 -2
  145. package/agents/patterns/previews/record-detail/run-at-once.light.webp +0 -0
  146. package/agents/patterns/previews/record-detail/work-on-it.dark.webp +0 -0
  147. package/agents/patterns/previews/record-detail/work-on-it.html +2 -2
  148. package/agents/patterns/previews/record-detail/work-on-it.light.webp +0 -0
  149. package/agents/patterns/previews/rhythm/between-containers.dark.webp +0 -0
  150. package/agents/patterns/previews/rhythm/between-containers.light.webp +0 -0
  151. package/agents/patterns/previews/rhythm/between-fields.dark.webp +0 -0
  152. package/agents/patterns/previews/rhythm/between-fields.light.webp +0 -0
  153. package/agents/patterns/previews/rhythm/between-groups.light.webp +0 -0
  154. package/agents/patterns/previews/rhythm/between-sections.dark.webp +0 -0
  155. package/agents/patterns/previews/rhythm/between-sections.light.webp +0 -0
  156. package/agents/patterns/previews/rhythm/inline.light.webp +0 -0
  157. package/agents/patterns/previews/rhythm/inset.dark.webp +0 -0
  158. package/agents/patterns/previews/rhythm/inset.light.webp +0 -0
  159. package/agents/patterns/previews/rhythm/title-content.dark.webp +0 -0
  160. package/agents/patterns/previews/rhythm/title-content.light.webp +0 -0
  161. package/agents/patterns/previews/surfaces/band.dark.webp +0 -0
  162. package/agents/patterns/previews/surfaces/band.html +2 -2
  163. package/agents/patterns/previews/surfaces/band.light.webp +0 -0
  164. package/agents/patterns/previews/surfaces/canvas.dark.webp +0 -0
  165. package/agents/patterns/previews/surfaces/canvas.html +2 -2
  166. package/agents/patterns/previews/surfaces/canvas.light.webp +0 -0
  167. package/agents/patterns/previews/surfaces/card.dark.webp +0 -0
  168. package/agents/patterns/previews/surfaces/card.light.webp +0 -0
  169. package/agents/patterns/previews/surfaces/dialog.dark.webp +0 -0
  170. package/agents/patterns/previews/surfaces/dialog.light.webp +0 -0
  171. package/agents/patterns/previews/surfaces/edit-actions.dark.webp +0 -0
  172. package/agents/patterns/previews/surfaces/edit-actions.light.webp +0 -0
  173. package/agents/patterns/previews/surfaces/intro-band.dark.webp +0 -0
  174. package/agents/patterns/previews/surfaces/intro-band.html +66 -0
  175. package/agents/patterns/previews/surfaces/intro-band.light.webp +0 -0
  176. package/agents/patterns/previews/surfaces/section.dark.webp +0 -0
  177. package/agents/patterns/previews/surfaces/section.light.webp +0 -0
  178. package/agents/patterns/previews/titles/dialog.dark.webp +0 -0
  179. package/agents/patterns/previews/titles/dialog.light.webp +0 -0
  180. package/agents/patterns/previews/titles/group.light.webp +0 -0
  181. package/agents/patterns/previews/titles/page.dark.webp +0 -0
  182. package/agents/patterns/previews/titles/page.light.webp +0 -0
  183. package/agents/patterns/previews/titles/part.light.webp +0 -0
  184. package/agents/patterns/previews/titles/section.light.webp +0 -0
  185. package/agents/patterns/previews/widths/dialog.dark.webp +0 -0
  186. package/agents/patterns/previews/widths/dialog.light.webp +0 -0
  187. package/agents/patterns/previews/widths/field.dark.webp +0 -0
  188. package/agents/patterns/previews/widths/field.light.webp +0 -0
  189. package/agents/patterns/previews/widths/form.dark.webp +0 -0
  190. package/agents/patterns/previews/widths/form.light.webp +0 -0
  191. package/agents/patterns/previews/widths/page.dark.webp +0 -0
  192. package/agents/patterns/previews/widths/page.html +2 -2
  193. package/agents/patterns/previews/widths/page.light.webp +0 -0
  194. package/agents/patterns/previews/widths/reading.dark.webp +0 -0
  195. package/agents/patterns/previews/widths/reading.light.webp +0 -0
  196. package/agents/patterns/rhythm.md +2 -1
  197. package/agents/patterns/surfaces.md +53 -14
  198. package/agents/patterns/titles.md +19 -17
  199. package/agents/patterns/widths.md +4 -3
  200. package/agents/patterns.md +9 -8
  201. package/agents/theming.md +12 -0
  202. package/dist/cjs/{aria-CzO5Rp1y.js → aria-r1anAHBr.js} +12 -0
  203. package/dist/cjs/{floating-controller-DaFymQCT.js → floating-controller-B21tqid0.js} +52 -5
  204. package/dist/cjs/{floating-ui.dom-VQ_HnnRe.js → floating-ui.dom-1Z4VE-PH.js} +1 -0
  205. package/dist/cjs/{index-BQNHYWJg.js → index-B99V_UhC.js} +87 -44
  206. package/dist/cjs/{index-Bg68W-da.js → index-CFEj7WVH.js} +12 -1
  207. package/dist/cjs/index.cjs.js +45 -3
  208. package/dist/cjs/loader.cjs.js +2 -2
  209. package/dist/cjs/{locale-CaR39iYg.js → locale-6jikg4jE.js} +1 -1
  210. package/dist/cjs/magma-components.cjs.js +3 -3
  211. package/dist/cjs/mds-accordion-item.cjs.entry.js +10 -7
  212. package/dist/cjs/mds-accordion-timer-item.cjs.entry.js +10 -7
  213. package/dist/cjs/mds-accordion-timer.cjs.entry.js +4 -3
  214. package/dist/cjs/mds-accordion.cjs.entry.js +5 -4
  215. package/dist/cjs/mds-author.cjs.entry.js +4 -3
  216. package/dist/cjs/mds-avatar-stack-item.cjs.entry.js +4 -3
  217. package/dist/cjs/mds-avatar-stack.cjs.entry.js +4 -3
  218. package/dist/cjs/mds-avatar.cjs.entry.js +5 -4
  219. package/dist/cjs/mds-badge.cjs.entry.js +6 -5
  220. package/dist/cjs/mds-banner_3.cjs.entry.js +56 -27
  221. package/dist/cjs/mds-benchmark-bar.cjs.entry.js +4 -3
  222. package/dist/cjs/mds-bibliography.cjs.entry.js +4 -3
  223. package/dist/cjs/mds-book.cjs.entry.js +8 -7
  224. package/dist/cjs/mds-breadcrumb-item.cjs.entry.js +4 -3
  225. package/dist/cjs/mds-breadcrumb.cjs.entry.js +6 -5
  226. package/dist/cjs/mds-button-dropdown.cjs.entry.js +10 -7
  227. package/dist/cjs/mds-button-group.cjs.entry.js +5 -4
  228. package/dist/cjs/mds-button_3.cjs.entry.js +86 -21
  229. package/dist/cjs/mds-calendar_2.cjs.entry.js +190 -305
  230. package/dist/cjs/mds-card-content.cjs.entry.js +4 -3
  231. package/dist/cjs/mds-card-footer.cjs.entry.js +5 -4
  232. package/dist/cjs/mds-card-header.cjs.entry.js +4 -3
  233. package/dist/cjs/mds-card-media.cjs.entry.js +4 -3
  234. package/dist/cjs/mds-card.cjs.entry.js +6 -5
  235. package/dist/cjs/mds-details.cjs.entry.js +5 -4
  236. package/dist/cjs/mds-dropdown.cjs.entry.js +48 -19
  237. package/dist/cjs/mds-emoji.cjs.entry.js +5 -4
  238. package/dist/cjs/mds-entity.cjs.entry.js +5 -4
  239. package/dist/cjs/mds-file-preview.cjs.entry.js +8 -7
  240. package/dist/cjs/mds-file.cjs.entry.js +8 -7
  241. package/dist/cjs/mds-filter-item.cjs.entry.js +8 -7
  242. package/dist/cjs/mds-filter.cjs.entry.js +7 -6
  243. package/dist/cjs/mds-header-bar.cjs.entry.js +6 -5
  244. package/dist/cjs/mds-header.cjs.entry.js +6 -5
  245. package/dist/cjs/mds-horizontal-scroll.cjs.entry.js +6 -5
  246. package/dist/cjs/mds-hr.cjs.entry.js +5 -4
  247. package/dist/cjs/mds-img.cjs.entry.js +5 -4
  248. package/dist/cjs/mds-input-date-range-preselection.cjs.entry.js +3 -2
  249. package/dist/cjs/mds-input-date-range.cjs.entry.js +127 -32
  250. package/dist/cjs/mds-input-date.cjs.entry.js +26 -12
  251. package/dist/cjs/mds-input-field.cjs.entry.js +3 -2
  252. package/dist/cjs/mds-input-otp.cjs.entry.js +5 -4
  253. package/dist/cjs/mds-input-range-value.cjs.entry.js +18 -0
  254. package/dist/cjs/mds-input-range.cjs.entry.js +410 -29
  255. package/dist/cjs/mds-input-select.cjs.entry.js +9 -8
  256. package/dist/cjs/mds-input-switch_2.cjs.entry.js +11 -9
  257. package/dist/cjs/mds-input-tip_2.cjs.entry.js +17 -12
  258. package/dist/cjs/mds-input-upload.cjs.entry.js +10 -9
  259. package/dist/cjs/mds-input.cjs.entry.js +293 -36
  260. package/dist/cjs/mds-keyboard-key.cjs.entry.js +6 -5
  261. package/dist/cjs/mds-keyboard.cjs.entry.js +7 -6
  262. package/dist/cjs/mds-kpi-item.cjs.entry.js +6 -5
  263. package/dist/cjs/mds-kpi.cjs.entry.js +4 -3
  264. package/dist/cjs/mds-label.cjs.entry.js +7 -6
  265. package/dist/cjs/mds-link.cjs.entry.js +9 -8
  266. package/dist/cjs/mds-list-item.cjs.entry.js +4 -3
  267. package/dist/cjs/mds-list.cjs.entry.js +4 -3
  268. package/dist/cjs/mds-mention.cjs.entry.js +6 -5
  269. package/dist/cjs/mds-modal.cjs.entry.js +37 -17
  270. package/dist/cjs/mds-note.cjs.entry.js +7 -6
  271. package/dist/cjs/mds-notification.cjs.entry.js +7 -6
  272. package/dist/cjs/mds-paginator-item.cjs.entry.js +5 -4
  273. package/dist/cjs/mds-paginator.cjs.entry.js +7 -6
  274. package/dist/cjs/mds-policy-ai.cjs.entry.js +6 -5
  275. package/dist/cjs/mds-pref-animation.cjs.entry.js +6 -5
  276. package/dist/cjs/mds-pref-consumption.cjs.entry.js +6 -5
  277. package/dist/cjs/mds-pref-contrast.cjs.entry.js +6 -5
  278. package/dist/cjs/mds-pref-language-item.cjs.entry.js +6 -5
  279. package/dist/cjs/mds-pref-language.cjs.entry.js +6 -5
  280. package/dist/cjs/mds-pref-mode.cjs.entry.js +25 -15
  281. package/dist/cjs/mds-pref-theme-item.cjs.entry.js +4 -3
  282. package/dist/cjs/mds-pref-theme.cjs.entry.js +34 -10
  283. package/dist/cjs/mds-pref.cjs.entry.js +12 -28
  284. package/dist/cjs/mds-price-table-features-cell.cjs.entry.js +6 -5
  285. package/dist/cjs/mds-price-table-features-row.cjs.entry.js +6 -5
  286. package/dist/cjs/mds-price-table-features.cjs.entry.js +5 -4
  287. package/dist/cjs/mds-price-table-header.cjs.entry.js +4 -3
  288. package/dist/cjs/mds-price-table-list-item.cjs.entry.js +4 -3
  289. package/dist/cjs/mds-price-table-list.cjs.entry.js +6 -5
  290. package/dist/cjs/mds-price-table.cjs.entry.js +4 -3
  291. package/dist/cjs/mds-progress_2.cjs.entry.js +14 -9
  292. package/dist/cjs/mds-push-notification-item.cjs.entry.js +7 -6
  293. package/dist/cjs/mds-push-notification.cjs.entry.js +7 -6
  294. package/dist/cjs/mds-quote.cjs.entry.js +5 -4
  295. package/dist/cjs/mds-radial-menu-item.cjs.entry.js +4 -3
  296. package/dist/cjs/mds-radial-menu.cjs.entry.js +9 -8
  297. package/dist/cjs/mds-separator.cjs.entry.js +5 -4
  298. package/dist/cjs/mds-status-bar.cjs.entry.js +6 -5
  299. package/dist/cjs/mds-stepper-bar-item.cjs.entry.js +7 -6
  300. package/dist/cjs/mds-stepper-bar.cjs.entry.js +6 -6
  301. package/dist/cjs/mds-tab-bar-item.cjs.entry.js +7 -6
  302. package/dist/cjs/mds-tab-bar.cjs.entry.js +6 -5
  303. package/dist/cjs/mds-tab_2.cjs.entry.js +43 -19
  304. package/dist/cjs/mds-table-body.cjs.entry.js +5 -4
  305. package/dist/cjs/mds-table-footer.cjs.entry.js +5 -4
  306. package/dist/cjs/mds-table-header-cell.cjs.entry.js +5 -4
  307. package/dist/cjs/mds-table-header.cjs.entry.js +14 -14
  308. package/dist/cjs/mds-table-row.cjs.entry.js +7 -6
  309. package/dist/cjs/mds-table.cjs.entry.js +43 -15
  310. package/dist/cjs/mds-text.cjs.entry.js +5 -4
  311. package/dist/cjs/mds-toast-region.cjs.entry.js +4 -3
  312. package/dist/cjs/mds-toast.cjs.entry.js +6 -5
  313. package/dist/cjs/mds-tooltip.cjs.entry.js +35 -16
  314. package/dist/cjs/mds-tree-item.cjs.entry.js +6 -5
  315. package/dist/cjs/mds-tree.cjs.entry.js +4 -3
  316. package/dist/cjs/mds-url-view.cjs.entry.js +7 -19
  317. package/dist/cjs/mds-usage.cjs.entry.js +7 -6
  318. package/dist/cjs/mds-video-wall.cjs.entry.js +5 -4
  319. package/dist/cjs/mds-zero.cjs.entry.js +15 -5
  320. package/dist/cjs/{navigation-5yeOyO6F.js → navigation-Dxea9mKE.js} +7 -0
  321. package/dist/cjs/{preference-CQQ3eb9W.js → preference-DTUJPGHS.js} +21 -1
  322. package/dist/collection/collection-manifest.json +2 -1
  323. package/dist/collection/common/aria.js +12 -1
  324. package/dist/collection/common/floating-controller.js +50 -3
  325. package/dist/collection/common/navigation.js +7 -0
  326. package/dist/collection/common/preference.js +19 -1
  327. package/dist/collection/common/validity/index.js +3 -0
  328. package/dist/collection/components/mds-accordion/AGENTS.md +2 -2
  329. package/dist/collection/components/mds-accordion/documentation.json +5 -4
  330. package/dist/collection/components/mds-accordion/examples.md +3 -3
  331. package/dist/collection/components/mds-accordion/mds-accordion.js +1 -1
  332. package/dist/collection/components/mds-accordion-item/AGENTS.md +5 -3
  333. package/dist/collection/components/mds-accordion-item/documentation.json +60 -5
  334. package/dist/collection/components/mds-accordion-item/examples.md +5 -3
  335. package/dist/collection/components/mds-accordion-item/mds-accordion-item.css +9 -0
  336. package/dist/collection/components/mds-accordion-item/mds-accordion-item.js +32 -4
  337. package/dist/collection/components/mds-accordion-timer/AGENTS.md +1 -1
  338. package/dist/collection/components/mds-accordion-timer/documentation.json +3 -2
  339. package/dist/collection/components/mds-accordion-timer/mds-accordion-timer.js +1 -1
  340. package/dist/collection/components/mds-accordion-timer-item/AGENTS.md +6 -4
  341. package/dist/collection/components/mds-accordion-timer-item/documentation.json +64 -9
  342. package/dist/collection/components/mds-accordion-timer-item/examples.md +5 -3
  343. package/dist/collection/components/mds-accordion-timer-item/mds-accordion-timer-item.css +9 -0
  344. package/dist/collection/components/mds-accordion-timer-item/mds-accordion-timer-item.js +32 -4
  345. package/dist/collection/components/mds-author/AGENTS.md +1 -1
  346. package/dist/collection/components/mds-author/documentation.json +3 -2
  347. package/dist/collection/components/mds-author/mds-author.js +1 -1
  348. package/dist/collection/components/mds-avatar/AGENTS.md +1 -1
  349. package/dist/collection/components/mds-avatar/documentation.json +4 -3
  350. package/dist/collection/components/mds-avatar/mds-avatar.js +1 -1
  351. package/dist/collection/components/mds-avatar-stack/AGENTS.md +1 -1
  352. package/dist/collection/components/mds-avatar-stack/documentation.json +4 -3
  353. package/dist/collection/components/mds-avatar-stack/mds-avatar-stack.js +1 -1
  354. package/dist/collection/components/mds-avatar-stack-item/AGENTS.md +1 -1
  355. package/dist/collection/components/mds-avatar-stack-item/documentation.json +4 -3
  356. package/dist/collection/components/mds-avatar-stack-item/mds-avatar-stack-item.js +1 -1
  357. package/dist/collection/components/mds-badge/AGENTS.md +1 -1
  358. package/dist/collection/components/mds-badge/documentation.json +3 -2
  359. package/dist/collection/components/mds-badge/mds-badge.css +15 -10
  360. package/dist/collection/components/mds-badge/mds-badge.js +1 -1
  361. package/dist/collection/components/mds-banner/AGENTS.md +4 -1
  362. package/dist/collection/components/mds-banner/documentation.json +45 -6
  363. package/dist/collection/components/mds-banner/examples.md +15 -9
  364. package/dist/collection/components/mds-banner/mds-banner.js +63 -19
  365. package/dist/collection/components/mds-banner/meta/dictionary.js +7 -0
  366. package/dist/collection/components/mds-banner/meta/types.js +1 -0
  367. package/dist/collection/components/mds-banner/mistakes.md +20 -0
  368. package/dist/collection/components/mds-benchmark-bar/AGENTS.md +1 -1
  369. package/dist/collection/components/mds-benchmark-bar/documentation.json +3 -2
  370. package/dist/collection/components/mds-benchmark-bar/mds-benchmark-bar.js +1 -1
  371. package/dist/collection/components/mds-bibliography/AGENTS.md +1 -1
  372. package/dist/collection/components/mds-bibliography/documentation.json +3 -2
  373. package/dist/collection/components/mds-bibliography/mds-bibliography.js +1 -1
  374. package/dist/collection/components/mds-book/AGENTS.md +1 -1
  375. package/dist/collection/components/mds-book/documentation.json +3 -2
  376. package/dist/collection/components/mds-book/mds-book.js +3 -3
  377. package/dist/collection/components/mds-breadcrumb/AGENTS.md +1 -1
  378. package/dist/collection/components/mds-breadcrumb/documentation.json +4 -3
  379. package/dist/collection/components/mds-breadcrumb/mds-breadcrumb.js +1 -1
  380. package/dist/collection/components/mds-breadcrumb-item/AGENTS.md +1 -1
  381. package/dist/collection/components/mds-breadcrumb-item/documentation.json +4 -3
  382. package/dist/collection/components/mds-breadcrumb-item/mds-breadcrumb-item.js +1 -1
  383. package/dist/collection/components/mds-button/AGENTS.md +9 -4
  384. package/dist/collection/components/mds-button/documentation.json +102 -8
  385. package/dist/collection/components/mds-button/examples.md +73 -0
  386. package/dist/collection/components/mds-button/mds-button.css +122 -14
  387. package/dist/collection/components/mds-button/mds-button.js +139 -13
  388. package/dist/collection/components/mds-button/mistakes.md +35 -0
  389. package/dist/collection/components/mds-button-dropdown/AGENTS.md +9 -2
  390. package/dist/collection/components/mds-button-dropdown/documentation.json +100 -6
  391. package/dist/collection/components/mds-button-dropdown/examples.md +16 -0
  392. package/dist/collection/components/mds-button-dropdown/mds-button-dropdown.css +12 -0
  393. package/dist/collection/components/mds-button-dropdown/mds-button-dropdown.js +69 -3
  394. package/dist/collection/components/mds-button-group/AGENTS.md +3 -2
  395. package/dist/collection/components/mds-button-group/documentation.json +5 -4
  396. package/dist/collection/components/mds-button-group/examples.md +16 -0
  397. package/dist/collection/components/mds-button-group/mds-button-group.css +13 -0
  398. package/dist/collection/components/mds-button-group/mds-button-group.js +1 -1
  399. package/dist/collection/components/mds-calendar/AGENTS.md +8 -4
  400. package/dist/collection/components/mds-calendar/documentation.json +45 -6
  401. package/dist/collection/components/mds-calendar/examples.md +17 -1
  402. package/dist/collection/components/mds-calendar/mds-calendar.css +4 -0
  403. package/dist/collection/components/mds-calendar/mds-calendar.js +206 -300
  404. package/dist/collection/components/mds-calendar/meta/types.js +1 -0
  405. package/dist/collection/components/mds-calendar/mistakes.md +1 -1
  406. package/dist/collection/components/mds-calendar-cell/AGENTS.md +4 -4
  407. package/dist/collection/components/mds-calendar-cell/documentation.json +38 -25
  408. package/dist/collection/components/mds-calendar-cell/examples.md +3 -3
  409. package/dist/collection/components/mds-calendar-cell/mds-calendar-cell.css +121 -84
  410. package/dist/collection/components/mds-calendar-cell/mds-calendar-cell.js +1 -1
  411. package/dist/collection/components/mds-card/AGENTS.md +4 -2
  412. package/dist/collection/components/mds-card/documentation.json +12 -5
  413. package/dist/collection/components/mds-card/examples.md +6 -1
  414. package/dist/collection/components/mds-card/mds-card.css +8 -0
  415. package/dist/collection/components/mds-card/mds-card.js +1 -1
  416. package/dist/collection/components/mds-card/mistakes.md +1 -1
  417. package/dist/collection/components/mds-card-content/AGENTS.md +1 -1
  418. package/dist/collection/components/mds-card-content/documentation.json +3 -2
  419. package/dist/collection/components/mds-card-content/mds-card-content.js +1 -1
  420. package/dist/collection/components/mds-card-footer/AGENTS.md +2 -2
  421. package/dist/collection/components/mds-card-footer/documentation.json +5 -4
  422. package/dist/collection/components/mds-card-footer/examples.md +1 -1
  423. package/dist/collection/components/mds-card-footer/mds-card-footer.css +9 -0
  424. package/dist/collection/components/mds-card-footer/mds-card-footer.js +1 -1
  425. package/dist/collection/components/mds-card-header/AGENTS.md +1 -1
  426. package/dist/collection/components/mds-card-header/documentation.json +3 -2
  427. package/dist/collection/components/mds-card-header/mds-card-header.js +1 -1
  428. package/dist/collection/components/mds-card-media/AGENTS.md +1 -1
  429. package/dist/collection/components/mds-card-media/documentation.json +3 -2
  430. package/dist/collection/components/mds-card-media/mds-card-media.js +1 -1
  431. package/dist/collection/components/mds-chip/AGENTS.md +5 -2
  432. package/dist/collection/components/mds-chip/documentation.json +38 -6
  433. package/dist/collection/components/mds-chip/examples.md +10 -0
  434. package/dist/collection/components/mds-chip/mds-chip.css +21 -2
  435. package/dist/collection/components/mds-chip/mds-chip.js +25 -1
  436. package/dist/collection/components/mds-chip/mistakes.md +25 -1
  437. package/dist/collection/components/mds-details/AGENTS.md +1 -1
  438. package/dist/collection/components/mds-details/documentation.json +3 -2
  439. package/dist/collection/components/mds-details/mds-details.js +1 -1
  440. package/dist/collection/components/mds-dropdown/AGENTS.md +1 -1
  441. package/dist/collection/components/mds-dropdown/documentation.json +4 -3
  442. package/dist/collection/components/mds-dropdown/mds-dropdown.css +12 -14
  443. package/dist/collection/components/mds-dropdown/mds-dropdown.js +40 -12
  444. package/dist/collection/components/mds-dropdown/mistakes.md +1 -1
  445. package/dist/collection/components/mds-emoji/AGENTS.md +1 -1
  446. package/dist/collection/components/mds-emoji/documentation.json +3 -2
  447. package/dist/collection/components/mds-emoji/mds-emoji.js +1 -1
  448. package/dist/collection/components/mds-entity/AGENTS.md +1 -1
  449. package/dist/collection/components/mds-entity/documentation.json +4 -3
  450. package/dist/collection/components/mds-entity/mds-entity.js +1 -1
  451. package/dist/collection/components/mds-file/AGENTS.md +1 -1
  452. package/dist/collection/components/mds-file/documentation.json +3 -2
  453. package/dist/collection/components/mds-file/mds-file.css +3 -2
  454. package/dist/collection/components/mds-file/mds-file.js +1 -1
  455. package/dist/collection/components/mds-file-preview/AGENTS.md +1 -1
  456. package/dist/collection/components/mds-file-preview/documentation.json +4 -3
  457. package/dist/collection/components/mds-file-preview/mds-file-preview.css +3 -2
  458. package/dist/collection/components/mds-file-preview/mds-file-preview.js +2 -2
  459. package/dist/collection/components/mds-filter/AGENTS.md +1 -1
  460. package/dist/collection/components/mds-filter/documentation.json +3 -2
  461. package/dist/collection/components/mds-filter/mds-filter.css +3 -2
  462. package/dist/collection/components/mds-filter/mds-filter.js +1 -1
  463. package/dist/collection/components/mds-filter-item/AGENTS.md +2 -2
  464. package/dist/collection/components/mds-filter-item/documentation.json +5 -4
  465. package/dist/collection/components/mds-filter-item/mds-filter-item.css +3 -2
  466. package/dist/collection/components/mds-filter-item/mds-filter-item.js +1 -1
  467. package/dist/collection/components/mds-filter-item/mistakes.md +16 -0
  468. package/dist/collection/components/mds-header/AGENTS.md +1 -1
  469. package/dist/collection/components/mds-header/documentation.json +4 -3
  470. package/dist/collection/components/mds-header/mds-header.css +3 -2
  471. package/dist/collection/components/mds-header/mds-header.js +1 -1
  472. package/dist/collection/components/mds-header-bar/AGENTS.md +1 -1
  473. package/dist/collection/components/mds-header-bar/documentation.json +4 -3
  474. package/dist/collection/components/mds-header-bar/mds-header-bar.js +1 -1
  475. package/dist/collection/components/mds-help/AGENTS.md +1 -1
  476. package/dist/collection/components/mds-help/documentation.json +3 -2
  477. package/dist/collection/components/mds-help/mds-help.js +1 -1
  478. package/dist/collection/components/mds-horizontal-scroll/AGENTS.md +1 -1
  479. package/dist/collection/components/mds-horizontal-scroll/documentation.json +4 -3
  480. package/dist/collection/components/mds-horizontal-scroll/mds-horizontal-scroll.js +1 -1
  481. package/dist/collection/components/mds-hr/AGENTS.md +1 -1
  482. package/dist/collection/components/mds-hr/documentation.json +3 -2
  483. package/dist/collection/components/mds-hr/mds-hr.js +1 -1
  484. package/dist/collection/components/mds-icon/AGENTS.md +2 -2
  485. package/dist/collection/components/mds-icon/documentation.json +5 -4
  486. package/dist/collection/components/mds-icon/examples.md +3 -3
  487. package/dist/collection/components/mds-icon/mds-icon.js +1 -1
  488. package/dist/collection/components/mds-icon/services/icons-set.service.js +43 -1
  489. package/dist/collection/components/mds-img/AGENTS.md +1 -1
  490. package/dist/collection/components/mds-img/documentation.json +4 -3
  491. package/dist/collection/components/mds-input/AGENTS.md +22 -18
  492. package/dist/collection/components/mds-input/documentation.json +33 -20
  493. package/dist/collection/components/mds-input/examples.md +20 -3
  494. package/dist/collection/components/mds-input/mds-input.css +131 -16
  495. package/dist/collection/components/mds-input/mds-input.js +236 -37
  496. package/dist/collection/components/mds-input/meta/color.js +19 -0
  497. package/dist/collection/components/mds-input/meta/input-type/InputValidationManager.js +5 -1
  498. package/dist/collection/components/mds-input/meta/validators.js +10 -0
  499. package/dist/collection/components/mds-input/meta/validity.js +5 -2
  500. package/dist/collection/components/mds-input/mistakes.md +15 -1
  501. package/dist/collection/components/mds-input-date/AGENTS.md +7 -7
  502. package/dist/collection/components/mds-input-date/documentation.json +8 -25
  503. package/dist/collection/components/mds-input-date/examples.md +1 -1
  504. package/dist/collection/components/mds-input-date/mds-input-date.css +20 -17
  505. package/dist/collection/components/mds-input-date/mds-input-date.js +21 -8
  506. package/dist/collection/components/mds-input-date-range/AGENTS.md +10 -7
  507. package/dist/collection/components/mds-input-date-range/documentation.json +17 -9
  508. package/dist/collection/components/mds-input-date-range/examples.md +12 -1
  509. package/dist/collection/components/mds-input-date-range/mds-input-date-range.css +18 -2
  510. package/dist/collection/components/mds-input-date-range/mds-input-date-range.js +90 -27
  511. package/dist/collection/components/mds-input-date-range-preselection/AGENTS.md +1 -1
  512. package/dist/collection/components/mds-input-date-range-preselection/documentation.json +4 -3
  513. package/dist/collection/components/mds-input-field/AGENTS.md +1 -1
  514. package/dist/collection/components/mds-input-field/documentation.json +3 -2
  515. package/dist/collection/components/mds-input-otp/AGENTS.md +1 -1
  516. package/dist/collection/components/mds-input-otp/documentation.json +4 -3
  517. package/dist/collection/components/mds-input-range/AGENTS.md +27 -8
  518. package/dist/collection/components/mds-input-range/documentation.json +31 -9
  519. package/dist/collection/components/mds-input-range/examples.md +41 -0
  520. package/dist/collection/components/mds-input-range/mds-input-range.css +71 -7
  521. package/dist/collection/components/mds-input-range/mds-input-range.js +440 -29
  522. package/dist/collection/components/mds-input-range/meta/event-detail.js +1 -0
  523. package/dist/collection/components/mds-input-range/mistakes.md +37 -0
  524. package/dist/collection/components/mds-input-range-value/AGENTS.md +43 -0
  525. package/dist/collection/components/mds-input-range-value/documentation.json +77 -0
  526. package/dist/collection/components/mds-input-range-value/examples.md +66 -0
  527. package/dist/collection/components/mds-input-range-value/mds-input-range-value.css +6 -0
  528. package/dist/collection/components/mds-input-range-value/mds-input-range-value.js +50 -0
  529. package/dist/collection/components/mds-input-range-value/mistakes.md +56 -0
  530. package/dist/collection/components/mds-input-select/AGENTS.md +2 -2
  531. package/dist/collection/components/mds-input-select/documentation.json +4 -3
  532. package/dist/collection/components/mds-input-select/mds-input-select.css +24 -30
  533. package/dist/collection/components/mds-input-select/mds-input-select.js +2 -2
  534. package/dist/collection/components/mds-input-switch/AGENTS.md +1 -1
  535. package/dist/collection/components/mds-input-switch/documentation.json +3 -2
  536. package/dist/collection/components/mds-input-switch/mds-input-switch.css +3 -2
  537. package/dist/collection/components/mds-input-switch/mds-input-switch.js +1 -1
  538. package/dist/collection/components/mds-input-tip/AGENTS.md +7 -6
  539. package/dist/collection/components/mds-input-tip/documentation.json +17 -10
  540. package/dist/collection/components/mds-input-tip/examples.md +2 -2
  541. package/dist/collection/components/mds-input-tip/mds-input-tip.css +15 -17
  542. package/dist/collection/components/mds-input-tip/mds-input-tip.js +9 -6
  543. package/dist/collection/components/mds-input-tip-item/AGENTS.md +1 -1
  544. package/dist/collection/components/mds-input-tip-item/documentation.json +3 -2
  545. package/dist/collection/components/mds-input-tip-item/mds-input-tip-item.js +2 -2
  546. package/dist/collection/components/mds-input-tip-item/meta/dictionary.js +1 -1
  547. package/dist/collection/components/mds-input-upload/AGENTS.md +1 -1
  548. package/dist/collection/components/mds-input-upload/documentation.json +4 -3
  549. package/dist/collection/components/mds-input-upload/mds-input-upload.js +5 -5
  550. package/dist/collection/components/mds-keyboard/AGENTS.md +1 -1
  551. package/dist/collection/components/mds-keyboard/documentation.json +4 -3
  552. package/dist/collection/components/mds-keyboard/mds-keyboard.css +3 -2
  553. package/dist/collection/components/mds-keyboard/mds-keyboard.js +1 -1
  554. package/dist/collection/components/mds-keyboard-key/AGENTS.md +1 -1
  555. package/dist/collection/components/mds-keyboard-key/documentation.json +3 -2
  556. package/dist/collection/components/mds-keyboard-key/mds-keyboard-key.js +1 -1
  557. package/dist/collection/components/mds-kpi/AGENTS.md +1 -1
  558. package/dist/collection/components/mds-kpi/documentation.json +3 -2
  559. package/dist/collection/components/mds-kpi/mds-kpi.js +1 -1
  560. package/dist/collection/components/mds-kpi-item/AGENTS.md +1 -1
  561. package/dist/collection/components/mds-kpi-item/documentation.json +3 -2
  562. package/dist/collection/components/mds-kpi-item/mds-kpi-item.css +9 -6
  563. package/dist/collection/components/mds-kpi-item/mds-kpi-item.js +1 -1
  564. package/dist/collection/components/mds-label/AGENTS.md +1 -1
  565. package/dist/collection/components/mds-label/documentation.json +4 -3
  566. package/dist/collection/components/mds-label/mds-label.css +3 -2
  567. package/dist/collection/components/mds-label/mds-label.js +1 -1
  568. package/dist/collection/components/mds-link/AGENTS.md +1 -1
  569. package/dist/collection/components/mds-link/documentation.json +3 -2
  570. package/dist/collection/components/mds-link/mds-link.js +3 -3
  571. package/dist/collection/components/mds-list/AGENTS.md +1 -1
  572. package/dist/collection/components/mds-list/documentation.json +3 -2
  573. package/dist/collection/components/mds-list/mds-list.js +1 -1
  574. package/dist/collection/components/mds-list-item/AGENTS.md +1 -1
  575. package/dist/collection/components/mds-list-item/documentation.json +3 -2
  576. package/dist/collection/components/mds-list-item/mds-list-item.js +1 -1
  577. package/dist/collection/components/mds-mention/AGENTS.md +1 -1
  578. package/dist/collection/components/mds-mention/documentation.json +4 -3
  579. package/dist/collection/components/mds-mention/mds-mention.js +1 -1
  580. package/dist/collection/components/mds-modal/AGENTS.md +4 -3
  581. package/dist/collection/components/mds-modal/documentation.json +7 -6
  582. package/dist/collection/components/mds-modal/examples.md +2 -0
  583. package/dist/collection/components/mds-modal/mds-modal.css +3 -2
  584. package/dist/collection/components/mds-modal/mds-modal.js +32 -13
  585. package/dist/collection/components/mds-note/AGENTS.md +1 -1
  586. package/dist/collection/components/mds-note/documentation.json +4 -3
  587. package/dist/collection/components/mds-note/mds-note.css +3 -2
  588. package/dist/collection/components/mds-note/mds-note.js +1 -1
  589. package/dist/collection/components/mds-notification/AGENTS.md +1 -1
  590. package/dist/collection/components/mds-notification/documentation.json +3 -2
  591. package/dist/collection/components/mds-notification/mds-notification.js +1 -1
  592. package/dist/collection/components/mds-paginator/AGENTS.md +1 -1
  593. package/dist/collection/components/mds-paginator/documentation.json +3 -2
  594. package/dist/collection/components/mds-paginator/mds-paginator.css +3 -2
  595. package/dist/collection/components/mds-paginator/mds-paginator.js +1 -1
  596. package/dist/collection/components/mds-paginator-item/AGENTS.md +1 -1
  597. package/dist/collection/components/mds-paginator-item/documentation.json +3 -2
  598. package/dist/collection/components/mds-paginator-item/mds-paginator-item.js +1 -1
  599. package/dist/collection/components/mds-policy-ai/AGENTS.md +1 -1
  600. package/dist/collection/components/mds-policy-ai/documentation.json +4 -3
  601. package/dist/collection/components/mds-policy-ai/mds-policy-ai.js +1 -1
  602. package/dist/collection/components/mds-pref/AGENTS.md +6 -3
  603. package/dist/collection/components/mds-pref/documentation.json +32 -10
  604. package/dist/collection/components/mds-pref/examples.md +15 -1
  605. package/dist/collection/components/mds-pref/mds-pref.js +26 -30
  606. package/dist/collection/components/mds-pref/mistakes.md +1 -1
  607. package/dist/collection/components/mds-pref-animation/AGENTS.md +1 -1
  608. package/dist/collection/components/mds-pref-animation/documentation.json +4 -3
  609. package/dist/collection/components/mds-pref-animation/mds-pref-animation.js +1 -1
  610. package/dist/collection/components/mds-pref-consumption/AGENTS.md +1 -1
  611. package/dist/collection/components/mds-pref-consumption/documentation.json +4 -3
  612. package/dist/collection/components/mds-pref-consumption/mds-pref-consumption.js +1 -1
  613. package/dist/collection/components/mds-pref-contrast/AGENTS.md +1 -1
  614. package/dist/collection/components/mds-pref-contrast/documentation.json +4 -3
  615. package/dist/collection/components/mds-pref-contrast/mds-pref-contrast.js +1 -1
  616. package/dist/collection/components/mds-pref-language/AGENTS.md +2 -2
  617. package/dist/collection/components/mds-pref-language/documentation.json +5 -4
  618. package/dist/collection/components/mds-pref-language/mds-pref-language.js +1 -1
  619. package/dist/collection/components/mds-pref-language-item/AGENTS.md +1 -1
  620. package/dist/collection/components/mds-pref-language-item/documentation.json +4 -3
  621. package/dist/collection/components/mds-pref-language-item/mds-pref-language-item.js +1 -1
  622. package/dist/collection/components/mds-pref-mode/AGENTS.md +3 -2
  623. package/dist/collection/components/mds-pref-mode/documentation.json +7 -6
  624. package/dist/collection/components/mds-pref-mode/mds-pref-mode.css +2 -1
  625. package/dist/collection/components/mds-pref-mode/mds-pref-mode.js +20 -11
  626. package/dist/collection/components/mds-pref-mode/mistakes.md +1 -1
  627. package/dist/collection/components/mds-pref-theme/AGENTS.md +6 -5
  628. package/dist/collection/components/mds-pref-theme/documentation.json +9 -8
  629. package/dist/collection/components/mds-pref-theme/examples.md +1 -1
  630. package/dist/collection/components/mds-pref-theme/mds-pref-theme.js +32 -9
  631. package/dist/collection/components/mds-pref-theme/mistakes.md +1 -1
  632. package/dist/collection/components/mds-pref-theme-item/AGENTS.md +2 -2
  633. package/dist/collection/components/mds-pref-theme-item/documentation.json +5 -4
  634. package/dist/collection/components/mds-pref-theme-item/mds-pref-theme-item.js +1 -1
  635. package/dist/collection/components/mds-price-table/AGENTS.md +1 -1
  636. package/dist/collection/components/mds-price-table/documentation.json +3 -2
  637. package/dist/collection/components/mds-price-table/mds-price-table.js +1 -1
  638. package/dist/collection/components/mds-price-table-features/AGENTS.md +1 -1
  639. package/dist/collection/components/mds-price-table-features/documentation.json +3 -2
  640. package/dist/collection/components/mds-price-table-features/mds-price-table-features.js +1 -1
  641. package/dist/collection/components/mds-price-table-features-cell/AGENTS.md +1 -1
  642. package/dist/collection/components/mds-price-table-features-cell/documentation.json +3 -2
  643. package/dist/collection/components/mds-price-table-features-cell/mds-price-table-features-cell.css +3 -2
  644. package/dist/collection/components/mds-price-table-features-cell/mds-price-table-features-cell.js +1 -1
  645. package/dist/collection/components/mds-price-table-features-row/AGENTS.md +1 -1
  646. package/dist/collection/components/mds-price-table-features-row/documentation.json +3 -2
  647. package/dist/collection/components/mds-price-table-features-row/mds-price-table-features-row.css +3 -2
  648. package/dist/collection/components/mds-price-table-features-row/mds-price-table-features-row.js +1 -1
  649. package/dist/collection/components/mds-price-table-header/AGENTS.md +1 -1
  650. package/dist/collection/components/mds-price-table-header/documentation.json +3 -2
  651. package/dist/collection/components/mds-price-table-header/mds-price-table-header.js +1 -1
  652. package/dist/collection/components/mds-price-table-list/AGENTS.md +1 -1
  653. package/dist/collection/components/mds-price-table-list/documentation.json +3 -2
  654. package/dist/collection/components/mds-price-table-list/mds-price-table-list.css +3 -2
  655. package/dist/collection/components/mds-price-table-list/mds-price-table-list.js +1 -1
  656. package/dist/collection/components/mds-price-table-list-item/AGENTS.md +1 -1
  657. package/dist/collection/components/mds-price-table-list-item/documentation.json +3 -2
  658. package/dist/collection/components/mds-price-table-list-item/mds-price-table-list-item.js +1 -1
  659. package/dist/collection/components/mds-progress/AGENTS.md +1 -1
  660. package/dist/collection/components/mds-progress/documentation.json +3 -2
  661. package/dist/collection/components/mds-progress/mds-progress.css +3 -2
  662. package/dist/collection/components/mds-progress/mds-progress.js +1 -1
  663. package/dist/collection/components/mds-push-notification/AGENTS.md +1 -1
  664. package/dist/collection/components/mds-push-notification/documentation.json +4 -3
  665. package/dist/collection/components/mds-push-notification/mds-push-notification.css +3 -2
  666. package/dist/collection/components/mds-push-notification/mds-push-notification.js +1 -1
  667. package/dist/collection/components/mds-push-notification-item/AGENTS.md +1 -1
  668. package/dist/collection/components/mds-push-notification-item/documentation.json +4 -3
  669. package/dist/collection/components/mds-push-notification-item/mds-push-notification-item.js +2 -2
  670. package/dist/collection/components/mds-quote/AGENTS.md +1 -1
  671. package/dist/collection/components/mds-quote/documentation.json +3 -2
  672. package/dist/collection/components/mds-quote/mds-quote.js +1 -1
  673. package/dist/collection/components/mds-radial-menu/AGENTS.md +1 -1
  674. package/dist/collection/components/mds-radial-menu/documentation.json +4 -3
  675. package/dist/collection/components/mds-radial-menu/mds-radial-menu.js +1 -1
  676. package/dist/collection/components/mds-radial-menu-item/AGENTS.md +1 -1
  677. package/dist/collection/components/mds-radial-menu-item/documentation.json +4 -3
  678. package/dist/collection/components/mds-radial-menu-item/mds-radial-menu-item.js +1 -1
  679. package/dist/collection/components/mds-radial-progress/AGENTS.md +1 -1
  680. package/dist/collection/components/mds-radial-progress/documentation.json +3 -2
  681. package/dist/collection/components/mds-radial-progress/mds-radial-progress.css +4 -2
  682. package/dist/collection/components/mds-radial-progress/mds-radial-progress.js +5 -2
  683. package/dist/collection/components/mds-separator/AGENTS.md +1 -1
  684. package/dist/collection/components/mds-separator/documentation.json +3 -2
  685. package/dist/collection/components/mds-separator/mds-separator.js +1 -1
  686. package/dist/collection/components/mds-spinner/AGENTS.md +1 -1
  687. package/dist/collection/components/mds-spinner/documentation.json +3 -2
  688. package/dist/collection/components/mds-spinner/mds-spinner.js +1 -1
  689. package/dist/collection/components/mds-status-bar/AGENTS.md +1 -1
  690. package/dist/collection/components/mds-status-bar/documentation.json +4 -3
  691. package/dist/collection/components/mds-status-bar/mds-status-bar.css +3 -2
  692. package/dist/collection/components/mds-status-bar/mds-status-bar.js +1 -1
  693. package/dist/collection/components/mds-stepper-bar/AGENTS.md +1 -1
  694. package/dist/collection/components/mds-stepper-bar/documentation.json +3 -2
  695. package/dist/collection/components/mds-stepper-bar/mds-stepper-bar.js +3 -4
  696. package/dist/collection/components/mds-stepper-bar-item/AGENTS.md +2 -2
  697. package/dist/collection/components/mds-stepper-bar-item/documentation.json +5 -4
  698. package/dist/collection/components/mds-stepper-bar-item/examples.md +1 -1
  699. package/dist/collection/components/mds-stepper-bar-item/mds-stepper-bar-item.css +7 -2
  700. package/dist/collection/components/mds-stepper-bar-item/mds-stepper-bar-item.js +1 -1
  701. package/dist/collection/components/mds-tab/AGENTS.md +3 -3
  702. package/dist/collection/components/mds-tab/documentation.json +8 -3
  703. package/dist/collection/components/mds-tab/mds-tab.css +3 -2
  704. package/dist/collection/components/mds-tab/mds-tab.js +34 -12
  705. package/dist/collection/components/mds-tab-bar/AGENTS.md +1 -1
  706. package/dist/collection/components/mds-tab-bar/documentation.json +3 -2
  707. package/dist/collection/components/mds-tab-bar/mds-tab-bar.css +3 -2
  708. package/dist/collection/components/mds-tab-bar/mds-tab-bar.js +1 -1
  709. package/dist/collection/components/mds-tab-bar-item/AGENTS.md +1 -1
  710. package/dist/collection/components/mds-tab-bar-item/documentation.json +3 -2
  711. package/dist/collection/components/mds-tab-bar-item/mds-tab-bar-item.css +3 -2
  712. package/dist/collection/components/mds-tab-bar-item/mds-tab-bar-item.js +1 -1
  713. package/dist/collection/components/mds-tab-item/AGENTS.md +2 -2
  714. package/dist/collection/components/mds-tab-item/documentation.json +8 -3
  715. package/dist/collection/components/mds-tab-item/mds-tab-item.js +1 -1
  716. package/dist/collection/components/mds-table/AGENTS.md +4 -4
  717. package/dist/collection/components/mds-table/documentation.json +10 -9
  718. package/dist/collection/components/mds-table/examples.md +21 -0
  719. package/dist/collection/components/mds-table/mds-table.css +6 -4
  720. package/dist/collection/components/mds-table/mds-table.js +42 -15
  721. package/dist/collection/components/mds-table-body/AGENTS.md +1 -1
  722. package/dist/collection/components/mds-table-body/documentation.json +3 -2
  723. package/dist/collection/components/mds-table-body/mds-table-body.js +1 -1
  724. package/dist/collection/components/mds-table-cell/AGENTS.md +1 -1
  725. package/dist/collection/components/mds-table-cell/documentation.json +3 -2
  726. package/dist/collection/components/mds-table-cell/mds-table-cell.js +1 -1
  727. package/dist/collection/components/mds-table-footer/AGENTS.md +1 -1
  728. package/dist/collection/components/mds-table-footer/documentation.json +3 -2
  729. package/dist/collection/components/mds-table-footer/mds-table-footer.js +1 -1
  730. package/dist/collection/components/mds-table-header/AGENTS.md +3 -3
  731. package/dist/collection/components/mds-table-header/documentation.json +6 -9
  732. package/dist/collection/components/mds-table-header/mds-table-header.js +9 -14
  733. package/dist/collection/components/mds-table-header/mistakes.md +1 -1
  734. package/dist/collection/components/mds-table-header-cell/AGENTS.md +1 -1
  735. package/dist/collection/components/mds-table-header-cell/documentation.json +4 -3
  736. package/dist/collection/components/mds-table-header-cell/mds-table-header-cell.js +1 -1
  737. package/dist/collection/components/mds-table-row/AGENTS.md +2 -2
  738. package/dist/collection/components/mds-table-row/documentation.json +4 -3
  739. package/dist/collection/components/mds-table-row/mds-table-row.js +2 -2
  740. package/dist/collection/components/mds-text/AGENTS.md +1 -1
  741. package/dist/collection/components/mds-text/documentation.json +3 -2
  742. package/dist/collection/components/mds-text/mds-text.js +1 -1
  743. package/dist/collection/components/mds-toast/AGENTS.md +1 -1
  744. package/dist/collection/components/mds-toast/documentation.json +4 -3
  745. package/dist/collection/components/mds-toast/mds-toast.js +1 -1
  746. package/dist/collection/components/mds-toast-region/AGENTS.md +1 -1
  747. package/dist/collection/components/mds-toast-region/documentation.json +3 -2
  748. package/dist/collection/components/mds-toast-region/mds-toast-region.js +1 -1
  749. package/dist/collection/components/mds-tooltip/AGENTS.md +1 -1
  750. package/dist/collection/components/mds-tooltip/documentation.json +3 -2
  751. package/dist/collection/components/mds-tooltip/mds-tooltip.css +4 -2
  752. package/dist/collection/components/mds-tooltip/mds-tooltip.js +27 -9
  753. package/dist/collection/components/mds-tree/AGENTS.md +1 -1
  754. package/dist/collection/components/mds-tree/documentation.json +3 -2
  755. package/dist/collection/components/mds-tree/mds-tree.js +1 -1
  756. package/dist/collection/components/mds-tree-item/AGENTS.md +1 -1
  757. package/dist/collection/components/mds-tree-item/documentation.json +4 -3
  758. package/dist/collection/components/mds-tree-item/mds-tree-item.js +1 -1
  759. package/dist/collection/components/mds-url-view/AGENTS.md +1 -1
  760. package/dist/collection/components/mds-url-view/documentation.json +4 -3
  761. package/dist/collection/components/mds-url-view/mds-url-view.css +3 -2
  762. package/dist/collection/components/mds-url-view/mds-url-view.js +1 -14
  763. package/dist/collection/components/mds-usage/AGENTS.md +1 -1
  764. package/dist/collection/components/mds-usage/documentation.json +3 -2
  765. package/dist/collection/components/mds-usage/mds-usage.css +3 -2
  766. package/dist/collection/components/mds-usage/mds-usage.js +1 -1
  767. package/dist/collection/components/mds-video-wall/AGENTS.md +1 -1
  768. package/dist/collection/components/mds-video-wall/documentation.json +3 -2
  769. package/dist/collection/components/mds-video-wall/mds-video-wall.js +1 -1
  770. package/dist/collection/components/mds-zero/AGENTS.md +7 -6
  771. package/dist/collection/components/mds-zero/documentation.json +6 -5
  772. package/dist/collection/components/mds-zero/examples.md +37 -19
  773. package/dist/collection/components/mds-zero/mds-zero.css +22 -23
  774. package/dist/collection/components/mds-zero/mds-zero.js +17 -1
  775. package/dist/collection/components/mds-zero/mistakes.md +46 -8
  776. package/dist/collection/fixtures/dark-mode.js +16 -0
  777. package/dist/collection/index.js +2 -20
  778. package/dist/collection/type/button.js +3 -0
  779. package/dist/collection/type/file-types.js +1 -1
  780. package/dist/collection/type/input.js +1 -0
  781. package/dist/components/index.d.ts +2 -0
  782. package/dist/components/index.js +1 -1
  783. package/dist/components/mds-accordion-item.js +1 -1
  784. package/dist/components/mds-accordion-timer-item.js +1 -1
  785. package/dist/components/mds-accordion-timer.js +1 -1
  786. package/dist/components/mds-accordion.js +1 -1
  787. package/dist/components/mds-author.js +1 -1
  788. package/dist/components/mds-avatar-stack-item.js +1 -1
  789. package/dist/components/mds-avatar-stack.js +1 -1
  790. package/dist/components/mds-avatar.js +1 -1
  791. package/dist/components/mds-badge.js +1 -1
  792. package/dist/components/mds-banner.js +1 -1
  793. package/dist/components/mds-benchmark-bar.js +1 -1
  794. package/dist/components/mds-bibliography.js +1 -1
  795. package/dist/components/mds-book.js +1 -1
  796. package/dist/components/mds-breadcrumb-item.js +1 -1
  797. package/dist/components/mds-breadcrumb.js +1 -1
  798. package/dist/components/mds-button-dropdown.js +1 -1
  799. package/dist/components/mds-button-group.js +1 -1
  800. package/dist/components/mds-button.js +1 -1
  801. package/dist/components/mds-calendar-cell.js +1 -1
  802. package/dist/components/mds-calendar.js +1 -1
  803. package/dist/components/mds-card-content.js +1 -1
  804. package/dist/components/mds-card-footer.js +1 -1
  805. package/dist/components/mds-card-header.js +1 -1
  806. package/dist/components/mds-card-media.js +1 -1
  807. package/dist/components/mds-card.js +1 -1
  808. package/dist/components/mds-chip.js +1 -1
  809. package/dist/components/mds-details.js +1 -1
  810. package/dist/components/mds-dropdown.js +1 -1
  811. package/dist/components/mds-emoji.js +3 -3
  812. package/dist/components/mds-entity.js +1 -1
  813. package/dist/components/mds-file-preview.js +1 -1
  814. package/dist/components/mds-file.js +1 -1
  815. package/dist/components/mds-filter-item.js +1 -1
  816. package/dist/components/mds-filter.js +1 -1
  817. package/dist/components/mds-header-bar.js +1 -1
  818. package/dist/components/mds-header.js +1 -1
  819. package/dist/components/mds-help.js +1 -1
  820. package/dist/components/mds-horizontal-scroll.js +1 -1
  821. package/dist/components/mds-hr.js +1 -1
  822. package/dist/components/mds-icon.js +1 -1
  823. package/dist/components/mds-img.js +1 -1
  824. package/dist/components/mds-input-date-range-preselection.js +1 -1
  825. package/dist/components/mds-input-date-range.js +1 -1
  826. package/dist/components/mds-input-date.js +1 -1
  827. package/dist/components/mds-input-field.js +1 -1
  828. package/dist/components/mds-input-otp.js +1 -1
  829. package/dist/components/mds-input-range-value.d.ts +11 -0
  830. package/dist/components/mds-input-range-value.js +1 -0
  831. package/dist/components/mds-input-range.js +1 -1
  832. package/dist/components/mds-input-select.js +1 -1
  833. package/dist/components/mds-input-switch.js +1 -1
  834. package/dist/components/mds-input-tip-item.js +1 -1
  835. package/dist/components/mds-input-tip.js +1 -1
  836. package/dist/components/mds-input-upload.js +1 -1
  837. package/dist/components/mds-input.js +1 -1
  838. package/dist/components/mds-keyboard-key.js +1 -1
  839. package/dist/components/mds-keyboard.js +1 -1
  840. package/dist/components/mds-kpi-item.js +1 -1
  841. package/dist/components/mds-kpi.js +1 -1
  842. package/dist/components/mds-label.js +1 -1
  843. package/dist/components/mds-link.js +1 -1
  844. package/dist/components/mds-list-item.js +1 -1
  845. package/dist/components/mds-list.js +1 -1
  846. package/dist/components/mds-mention.js +1 -1
  847. package/dist/components/mds-modal.js +1 -1
  848. package/dist/components/mds-note.js +1 -1
  849. package/dist/components/mds-notification.js +1 -1
  850. package/dist/components/mds-paginator-item.js +1 -1
  851. package/dist/components/mds-paginator.js +1 -1
  852. package/dist/components/mds-policy-ai.js +1 -1
  853. package/dist/components/mds-pref-animation.js +1 -1
  854. package/dist/components/mds-pref-consumption.js +1 -1
  855. package/dist/components/mds-pref-contrast.js +1 -1
  856. package/dist/components/mds-pref-language-item.js +1 -1
  857. package/dist/components/mds-pref-language.js +1 -1
  858. package/dist/components/mds-pref-mode.js +1 -1
  859. package/dist/components/mds-pref-theme-item.js +1 -1
  860. package/dist/components/mds-pref-theme.js +1 -1
  861. package/dist/components/mds-pref.js +1 -1
  862. package/dist/components/mds-price-table-features-cell.js +1 -1
  863. package/dist/components/mds-price-table-features-row.js +1 -1
  864. package/dist/components/mds-price-table-features.js +1 -1
  865. package/dist/components/mds-price-table-header.js +1 -1
  866. package/dist/components/mds-price-table-list-item.js +1 -1
  867. package/dist/components/mds-price-table-list.js +1 -1
  868. package/dist/components/mds-price-table.js +1 -1
  869. package/dist/components/mds-progress.js +1 -1
  870. package/dist/components/mds-push-notification-item.js +1 -1
  871. package/dist/components/mds-push-notification.js +1 -1
  872. package/dist/components/mds-quote.js +1 -1
  873. package/dist/components/mds-radial-menu-item.js +1 -1
  874. package/dist/components/mds-radial-menu.js +1 -1
  875. package/dist/components/mds-radial-progress.js +1 -1
  876. package/dist/components/mds-separator.js +1 -1
  877. package/dist/components/mds-spinner.js +1 -1
  878. package/dist/components/mds-status-bar.js +1 -1
  879. package/dist/components/mds-stepper-bar-item.js +1 -1
  880. package/dist/components/mds-stepper-bar.js +1 -1
  881. package/dist/components/mds-tab-bar-item.js +1 -1
  882. package/dist/components/mds-tab-bar.js +1 -1
  883. package/dist/components/mds-tab-item.js +1 -1
  884. package/dist/components/mds-tab.js +1 -1
  885. package/dist/components/mds-table-body.js +1 -1
  886. package/dist/components/mds-table-cell.js +1 -1
  887. package/dist/components/mds-table-footer.js +1 -1
  888. package/dist/components/mds-table-header-cell.js +1 -1
  889. package/dist/components/mds-table-header.js +1 -1
  890. package/dist/components/mds-table-row.js +1 -1
  891. package/dist/components/mds-table.js +1 -1
  892. package/dist/components/mds-text.js +1 -1
  893. package/dist/components/mds-toast-region.js +1 -1
  894. package/dist/components/mds-toast.js +1 -1
  895. package/dist/components/mds-tooltip.js +1 -1
  896. package/dist/components/mds-tree-item.js +1 -1
  897. package/dist/components/mds-tree.js +1 -1
  898. package/dist/components/mds-url-view.js +1 -1
  899. package/dist/components/mds-usage.js +1 -1
  900. package/dist/components/mds-video-wall.js +1 -1
  901. package/dist/components/mds-zero.js +1 -1
  902. package/dist/components/{p-CVRN4LDc.js → p-AWCYh8Xe.js} +1 -1
  903. package/dist/components/{p-CKnbQQUb.js → p-B-GgEAg7.js} +1 -1
  904. package/dist/components/p-B3npFzUR.js +1 -0
  905. package/dist/components/p-BD9VWE7b.js +1 -0
  906. package/dist/components/{p-DvDB_L_5.js → p-BFZN4zJ9.js} +1 -1
  907. package/dist/components/p-BG1fjwnd.js +1 -0
  908. package/dist/components/{p-ikNX7XDH.js → p-BNl6YWNN.js} +1 -1
  909. package/dist/components/p-Bg11_7lt.js +1 -0
  910. package/dist/components/p-BiJ4xa4V.js +1 -0
  911. package/dist/components/{p-CZjwSwe5.js → p-BmlDGlcB.js} +2 -2
  912. package/dist/components/p-C0m6B_kt.js +1 -0
  913. package/dist/components/{p-D_RIY063.js → p-C589Hkfn.js} +1 -1
  914. package/dist/{magma-components/p-BaFfIZGB.js → components/p-C7p9e0P3.js} +1 -1
  915. package/dist/components/{p-DdzJfsw7.js → p-C878c9Nu.js} +1 -1
  916. package/dist/components/{p-Br6-kva-.js → p-CDcB9Zdz.js} +1 -1
  917. package/dist/components/{p-BFDRt7-n.js → p-CS8s4gRV.js} +1 -1
  918. package/dist/components/p-CSw6DbKp.js +1 -0
  919. package/dist/components/p-CUT9aFzz.js +1 -0
  920. package/dist/components/p-CfCw1XZP.js +1 -0
  921. package/dist/components/{p-DhpcFZrc.js → p-Cjy1i94z.js} +1 -1
  922. package/dist/components/{p-gLo3t_qO.js → p-Cs80Zm2b.js} +2 -2
  923. package/dist/components/{p-BaynxVRZ.js → p-Cs8RIbsQ.js} +1 -1
  924. package/dist/components/p-CtEHhdv4.js +1 -0
  925. package/dist/components/{p-DOdUioZq.js → p-Cty6fegI.js} +1 -1
  926. package/dist/components/{p-COkn4Vtq.js → p-D7C-gjL6.js} +1 -1
  927. package/dist/components/{p-BiW6luA5.js → p-DKYN6Ikh.js} +1 -1
  928. package/dist/components/p-DvccsLwr.js +1 -0
  929. package/dist/components/p-DwKxtKwS.js +1 -0
  930. package/dist/components/{p-C_Pc94vn.js → p-DxNrlomi.js} +1 -1
  931. package/dist/components/p-G8GFHw3L.js +1 -0
  932. package/dist/components/p-MjWyZlga.js +1 -0
  933. package/dist/components/p-VoGfNJRY.js +1 -0
  934. package/dist/components/{p-DqdlT4UG.js → p-WFNxKo1V.js} +1 -1
  935. package/dist/components/{p-D8CloC8I.js → p-aZlZ1XB9.js} +1 -1
  936. package/dist/components/p-g2_CekDc.js +3 -0
  937. package/dist/components/p-kS9VRIWa.js +1 -0
  938. package/dist/components/{p-C7rDjrH4.js → p-oHBGZ2Av.js} +1 -1
  939. package/dist/documentation.json +788 -229
  940. package/dist/esm/{aria-Cvhn9asj.js → aria-DwKxtKwS.js} +12 -1
  941. package/dist/esm/{floating-controller-BVlbYYkf.js → floating-controller-DlFrvBTG.js} +52 -5
  942. package/dist/esm/{floating-ui.dom-BaFfIZGB.js → floating-ui.dom-C7p9e0P3.js} +1 -1
  943. package/dist/esm/{index-CvLLN-QH.js → index-CPibDZjX.js} +87 -44
  944. package/dist/esm/{index-BJVvHlvf.js → index-DWniH_Ge.js} +12 -1
  945. package/dist/esm/index.js +45 -3
  946. package/dist/esm/loader.js +3 -3
  947. package/dist/esm/{locale-B6cOkl4I.js → locale-B7Hw4niB.js} +1 -1
  948. package/dist/esm/magma-components.js +4 -4
  949. package/dist/esm/mds-accordion-item.entry.js +10 -7
  950. package/dist/esm/mds-accordion-timer-item.entry.js +10 -7
  951. package/dist/esm/mds-accordion-timer.entry.js +4 -3
  952. package/dist/esm/mds-accordion.entry.js +5 -4
  953. package/dist/esm/mds-author.entry.js +4 -3
  954. package/dist/esm/mds-avatar-stack-item.entry.js +4 -3
  955. package/dist/esm/mds-avatar-stack.entry.js +4 -3
  956. package/dist/esm/mds-avatar.entry.js +5 -4
  957. package/dist/esm/mds-badge.entry.js +6 -5
  958. package/dist/esm/mds-banner_3.entry.js +56 -27
  959. package/dist/esm/mds-benchmark-bar.entry.js +4 -3
  960. package/dist/esm/mds-bibliography.entry.js +4 -3
  961. package/dist/esm/mds-book.entry.js +8 -7
  962. package/dist/esm/mds-breadcrumb-item.entry.js +4 -3
  963. package/dist/esm/mds-breadcrumb.entry.js +6 -5
  964. package/dist/esm/mds-button-dropdown.entry.js +10 -7
  965. package/dist/esm/mds-button-group.entry.js +5 -4
  966. package/dist/esm/mds-button_3.entry.js +86 -21
  967. package/dist/esm/mds-calendar_2.entry.js +190 -305
  968. package/dist/esm/mds-card-content.entry.js +4 -3
  969. package/dist/esm/mds-card-footer.entry.js +5 -4
  970. package/dist/esm/mds-card-header.entry.js +4 -3
  971. package/dist/esm/mds-card-media.entry.js +4 -3
  972. package/dist/esm/mds-card.entry.js +6 -5
  973. package/dist/esm/mds-details.entry.js +5 -4
  974. package/dist/esm/mds-dropdown.entry.js +48 -19
  975. package/dist/esm/mds-emoji.entry.js +5 -4
  976. package/dist/esm/mds-entity.entry.js +5 -4
  977. package/dist/esm/mds-file-preview.entry.js +8 -7
  978. package/dist/esm/mds-file.entry.js +8 -7
  979. package/dist/esm/mds-filter-item.entry.js +8 -7
  980. package/dist/esm/mds-filter.entry.js +7 -6
  981. package/dist/esm/mds-header-bar.entry.js +6 -5
  982. package/dist/esm/mds-header.entry.js +6 -5
  983. package/dist/esm/mds-horizontal-scroll.entry.js +6 -5
  984. package/dist/esm/mds-hr.entry.js +5 -4
  985. package/dist/esm/mds-img.entry.js +5 -4
  986. package/dist/esm/mds-input-date-range-preselection.entry.js +3 -2
  987. package/dist/esm/mds-input-date-range.entry.js +127 -32
  988. package/dist/esm/mds-input-date.entry.js +26 -12
  989. package/dist/esm/mds-input-field.entry.js +3 -2
  990. package/dist/esm/mds-input-otp.entry.js +5 -4
  991. package/dist/esm/mds-input-range-value.entry.js +16 -0
  992. package/dist/esm/mds-input-range.entry.js +410 -29
  993. package/dist/esm/mds-input-select.entry.js +9 -8
  994. package/dist/esm/mds-input-switch_2.entry.js +11 -9
  995. package/dist/esm/mds-input-tip_2.entry.js +17 -12
  996. package/dist/esm/mds-input-upload.entry.js +10 -9
  997. package/dist/esm/mds-input.entry.js +293 -36
  998. package/dist/esm/mds-keyboard-key.entry.js +6 -5
  999. package/dist/esm/mds-keyboard.entry.js +7 -6
  1000. package/dist/esm/mds-kpi-item.entry.js +6 -5
  1001. package/dist/esm/mds-kpi.entry.js +4 -3
  1002. package/dist/esm/mds-label.entry.js +7 -6
  1003. package/dist/esm/mds-link.entry.js +9 -8
  1004. package/dist/esm/mds-list-item.entry.js +4 -3
  1005. package/dist/esm/mds-list.entry.js +4 -3
  1006. package/dist/esm/mds-mention.entry.js +6 -5
  1007. package/dist/esm/mds-modal.entry.js +37 -17
  1008. package/dist/esm/mds-note.entry.js +7 -6
  1009. package/dist/esm/mds-notification.entry.js +7 -6
  1010. package/dist/esm/mds-paginator-item.entry.js +5 -4
  1011. package/dist/esm/mds-paginator.entry.js +7 -6
  1012. package/dist/esm/mds-policy-ai.entry.js +6 -5
  1013. package/dist/esm/mds-pref-animation.entry.js +6 -5
  1014. package/dist/esm/mds-pref-consumption.entry.js +6 -5
  1015. package/dist/esm/mds-pref-contrast.entry.js +6 -5
  1016. package/dist/esm/mds-pref-language-item.entry.js +6 -5
  1017. package/dist/esm/mds-pref-language.entry.js +6 -5
  1018. package/dist/esm/mds-pref-mode.entry.js +25 -15
  1019. package/dist/esm/mds-pref-theme-item.entry.js +4 -3
  1020. package/dist/esm/mds-pref-theme.entry.js +34 -10
  1021. package/dist/esm/mds-pref.entry.js +12 -28
  1022. package/dist/esm/mds-price-table-features-cell.entry.js +6 -5
  1023. package/dist/esm/mds-price-table-features-row.entry.js +6 -5
  1024. package/dist/esm/mds-price-table-features.entry.js +5 -4
  1025. package/dist/esm/mds-price-table-header.entry.js +4 -3
  1026. package/dist/esm/mds-price-table-list-item.entry.js +4 -3
  1027. package/dist/esm/mds-price-table-list.entry.js +6 -5
  1028. package/dist/esm/mds-price-table.entry.js +4 -3
  1029. package/dist/esm/mds-progress_2.entry.js +14 -9
  1030. package/dist/esm/mds-push-notification-item.entry.js +7 -6
  1031. package/dist/esm/mds-push-notification.entry.js +7 -6
  1032. package/dist/esm/mds-quote.entry.js +5 -4
  1033. package/dist/esm/mds-radial-menu-item.entry.js +4 -3
  1034. package/dist/esm/mds-radial-menu.entry.js +9 -8
  1035. package/dist/esm/mds-separator.entry.js +5 -4
  1036. package/dist/esm/mds-status-bar.entry.js +6 -5
  1037. package/dist/esm/mds-stepper-bar-item.entry.js +7 -6
  1038. package/dist/esm/mds-stepper-bar.entry.js +6 -6
  1039. package/dist/esm/mds-tab-bar-item.entry.js +7 -6
  1040. package/dist/esm/mds-tab-bar.entry.js +6 -5
  1041. package/dist/esm/mds-tab_2.entry.js +43 -19
  1042. package/dist/esm/mds-table-body.entry.js +5 -4
  1043. package/dist/esm/mds-table-footer.entry.js +5 -4
  1044. package/dist/esm/mds-table-header-cell.entry.js +5 -4
  1045. package/dist/esm/mds-table-header.entry.js +14 -14
  1046. package/dist/esm/mds-table-row.entry.js +7 -6
  1047. package/dist/esm/mds-table.entry.js +43 -15
  1048. package/dist/esm/mds-text.entry.js +5 -4
  1049. package/dist/esm/mds-toast-region.entry.js +4 -3
  1050. package/dist/esm/mds-toast.entry.js +6 -5
  1051. package/dist/esm/mds-tooltip.entry.js +35 -16
  1052. package/dist/esm/mds-tree-item.entry.js +6 -5
  1053. package/dist/esm/mds-tree.entry.js +4 -3
  1054. package/dist/esm/mds-url-view.entry.js +7 -19
  1055. package/dist/esm/mds-usage.entry.js +7 -6
  1056. package/dist/esm/mds-video-wall.entry.js +5 -4
  1057. package/dist/esm/mds-zero.entry.js +15 -5
  1058. package/dist/esm/{navigation-Bz1eiKqd.js → navigation-To9IeLHs.js} +7 -0
  1059. package/dist/esm/{preference-C5XjgGCb.js → preference-CBMLGSf7.js} +20 -2
  1060. package/dist/esm-es5/aria-DwKxtKwS.js +12 -0
  1061. package/dist/esm-es5/{floating-controller-BVlbYYkf.js → floating-controller-DlFrvBTG.js} +32 -12
  1062. package/dist/esm-es5/{floating-ui.dom-BaFfIZGB.js → floating-ui.dom-C7p9e0P3.js} +18 -18
  1063. package/dist/esm-es5/{index-CvLLN-QH.js → index-CPibDZjX.js} +30 -27
  1064. package/dist/esm-es5/index-DWniH_Ge.js +13 -0
  1065. package/dist/esm-es5/index.js +47 -5
  1066. package/dist/esm-es5/loader.js +1 -1
  1067. package/dist/esm-es5/{locale-B6cOkl4I.js → locale-B7Hw4niB.js} +18 -18
  1068. package/dist/esm-es5/magma-components.js +3 -3
  1069. package/dist/esm-es5/mds-accordion-item.entry.js +6 -4
  1070. package/dist/esm-es5/mds-accordion-timer-item.entry.js +6 -4
  1071. package/dist/esm-es5/mds-accordion-timer.entry.js +4 -4
  1072. package/dist/esm-es5/mds-accordion.entry.js +4 -4
  1073. package/dist/esm-es5/mds-author.entry.js +1 -1
  1074. package/dist/esm-es5/mds-avatar-stack-item.entry.js +2 -2
  1075. package/dist/esm-es5/mds-avatar-stack.entry.js +2 -2
  1076. package/dist/esm-es5/mds-avatar.entry.js +7 -7
  1077. package/dist/esm-es5/mds-badge.entry.js +2 -2
  1078. package/dist/esm-es5/mds-banner_3.entry.js +25 -6
  1079. package/dist/esm-es5/mds-benchmark-bar.entry.js +3 -3
  1080. package/dist/esm-es5/mds-bibliography.entry.js +6 -6
  1081. package/dist/esm-es5/mds-book.entry.js +22 -22
  1082. package/dist/esm-es5/mds-breadcrumb-item.entry.js +2 -2
  1083. package/dist/esm-es5/mds-breadcrumb.entry.js +4 -4
  1084. package/dist/esm-es5/mds-button-dropdown.entry.js +6 -4
  1085. package/dist/esm-es5/mds-button-group.entry.js +1 -1
  1086. package/dist/esm-es5/mds-button_3.entry.js +45 -23
  1087. package/dist/esm-es5/mds-calendar_2.entry.js +56 -14
  1088. package/dist/esm-es5/mds-card-content.entry.js +1 -1
  1089. package/dist/esm-es5/mds-card-footer.entry.js +1 -1
  1090. package/dist/esm-es5/mds-card-header.entry.js +1 -1
  1091. package/dist/esm-es5/mds-card-media.entry.js +1 -1
  1092. package/dist/esm-es5/mds-card.entry.js +3 -3
  1093. package/dist/esm-es5/mds-details.entry.js +3 -3
  1094. package/dist/esm-es5/mds-dropdown.entry.js +30 -15
  1095. package/dist/esm-es5/mds-emoji.entry.js +44 -44
  1096. package/dist/esm-es5/mds-entity.entry.js +1 -1
  1097. package/dist/esm-es5/mds-file-preview.entry.js +8 -8
  1098. package/dist/esm-es5/mds-file.entry.js +7 -7
  1099. package/dist/esm-es5/mds-filter-item.entry.js +4 -4
  1100. package/dist/esm-es5/mds-filter.entry.js +7 -7
  1101. package/dist/esm-es5/mds-header-bar.entry.js +3 -3
  1102. package/dist/esm-es5/mds-header.entry.js +8 -8
  1103. package/dist/esm-es5/mds-horizontal-scroll.entry.js +13 -13
  1104. package/dist/esm-es5/mds-hr.entry.js +1 -1
  1105. package/dist/esm-es5/mds-img.entry.js +4 -4
  1106. package/dist/esm-es5/mds-input-date-range-preselection.entry.js +2 -2
  1107. package/dist/esm-es5/mds-input-date-range.entry.js +48 -15
  1108. package/dist/esm-es5/mds-input-date.entry.js +19 -10
  1109. package/dist/esm-es5/mds-input-field.entry.js +3 -3
  1110. package/dist/esm-es5/mds-input-otp.entry.js +5 -5
  1111. package/dist/esm-es5/mds-input-range-value.entry.js +1 -0
  1112. package/dist/esm-es5/mds-input-range.entry.js +93 -12
  1113. package/dist/esm-es5/mds-input-select.entry.js +8 -8
  1114. package/dist/esm-es5/mds-input-switch_2.entry.js +5 -5
  1115. package/dist/esm-es5/mds-input-tip_2.entry.js +9 -6
  1116. package/dist/esm-es5/mds-input-upload.entry.js +8 -8
  1117. package/dist/esm-es5/mds-input.entry.js +157 -52
  1118. package/dist/esm-es5/mds-keyboard-key.entry.js +2 -2
  1119. package/dist/esm-es5/mds-keyboard.entry.js +7 -7
  1120. package/dist/esm-es5/mds-kpi-item.entry.js +3 -3
  1121. package/dist/esm-es5/mds-kpi.entry.js +1 -1
  1122. package/dist/esm-es5/mds-label.entry.js +2 -2
  1123. package/dist/esm-es5/mds-link.entry.js +7 -7
  1124. package/dist/esm-es5/mds-list-item.entry.js +2 -2
  1125. package/dist/esm-es5/mds-list.entry.js +1 -1
  1126. package/dist/esm-es5/mds-mention.entry.js +2 -2
  1127. package/dist/esm-es5/mds-modal.entry.js +28 -16
  1128. package/dist/esm-es5/mds-note.entry.js +3 -3
  1129. package/dist/esm-es5/mds-notification.entry.js +8 -8
  1130. package/dist/esm-es5/mds-paginator-item.entry.js +3 -3
  1131. package/dist/esm-es5/mds-paginator.entry.js +3 -3
  1132. package/dist/esm-es5/mds-policy-ai.entry.js +2 -2
  1133. package/dist/esm-es5/mds-pref-animation.entry.js +4 -4
  1134. package/dist/esm-es5/mds-pref-consumption.entry.js +4 -4
  1135. package/dist/esm-es5/mds-pref-contrast.entry.js +4 -4
  1136. package/dist/esm-es5/mds-pref-language-item.entry.js +3 -3
  1137. package/dist/esm-es5/mds-pref-language.entry.js +9 -9
  1138. package/dist/esm-es5/mds-pref-mode.entry.js +14 -4
  1139. package/dist/esm-es5/mds-pref-theme-item.entry.js +5 -5
  1140. package/dist/esm-es5/mds-pref-theme.entry.js +25 -12
  1141. package/dist/esm-es5/mds-pref.entry.js +8 -13
  1142. package/dist/esm-es5/mds-price-table-features-cell.entry.js +2 -2
  1143. package/dist/esm-es5/mds-price-table-features-row.entry.js +1 -1
  1144. package/dist/esm-es5/mds-price-table-features.entry.js +1 -1
  1145. package/dist/esm-es5/mds-price-table-header.entry.js +1 -1
  1146. package/dist/esm-es5/mds-price-table-list-item.entry.js +2 -2
  1147. package/dist/esm-es5/mds-price-table-list.entry.js +2 -2
  1148. package/dist/esm-es5/mds-price-table.entry.js +1 -1
  1149. package/dist/esm-es5/mds-progress_2.entry.js +9 -5
  1150. package/dist/esm-es5/mds-push-notification-item.entry.js +3 -3
  1151. package/dist/esm-es5/mds-push-notification.entry.js +7 -7
  1152. package/dist/esm-es5/mds-quote.entry.js +2 -2
  1153. package/dist/esm-es5/mds-radial-menu-item.entry.js +2 -2
  1154. package/dist/esm-es5/mds-radial-menu.entry.js +4 -4
  1155. package/dist/esm-es5/mds-separator.entry.js +1 -1
  1156. package/dist/esm-es5/mds-status-bar.entry.js +2 -2
  1157. package/dist/esm-es5/mds-stepper-bar-item.entry.js +5 -5
  1158. package/dist/esm-es5/mds-stepper-bar.entry.js +8 -5
  1159. package/dist/esm-es5/mds-tab-bar-item.entry.js +4 -4
  1160. package/dist/esm-es5/mds-tab-bar.entry.js +2 -2
  1161. package/dist/esm-es5/mds-tab_2.entry.js +31 -11
  1162. package/dist/esm-es5/mds-table-body.entry.js +1 -1
  1163. package/dist/esm-es5/mds-table-footer.entry.js +2 -2
  1164. package/dist/esm-es5/mds-table-header-cell.entry.js +7 -7
  1165. package/dist/esm-es5/mds-table-header.entry.js +9 -8
  1166. package/dist/esm-es5/mds-table-row.entry.js +4 -4
  1167. package/dist/esm-es5/mds-table.entry.js +24 -11
  1168. package/dist/esm-es5/mds-text.entry.js +7 -7
  1169. package/dist/esm-es5/mds-toast-region.entry.js +5 -5
  1170. package/dist/esm-es5/mds-toast.entry.js +7 -7
  1171. package/dist/esm-es5/mds-tooltip.entry.js +12 -3
  1172. package/dist/esm-es5/mds-tree-item.entry.js +7 -7
  1173. package/dist/esm-es5/mds-tree.entry.js +5 -5
  1174. package/dist/esm-es5/mds-url-view.entry.js +2 -2
  1175. package/dist/esm-es5/mds-usage.entry.js +3 -3
  1176. package/dist/esm-es5/mds-video-wall.entry.js +2 -2
  1177. package/dist/esm-es5/mds-zero.entry.js +1 -1
  1178. package/dist/esm-es5/{navigation-Bz1eiKqd.js → navigation-To9IeLHs.js} +8 -1
  1179. package/dist/esm-es5/{preference-C5XjgGCb.js → preference-CBMLGSf7.js} +15 -5
  1180. package/dist/hydrate/index.js +2307 -1091
  1181. package/dist/hydrate/index.mjs +2307 -1091
  1182. package/dist/lint/core/patterns.d.ts +26 -16
  1183. package/dist/lint/core/patterns.js +55 -38
  1184. package/dist/lint/mcp/tools.json +7 -7
  1185. package/dist/magma-components/index.esm.js +1 -1
  1186. package/dist/magma-components/magma-components.esm.js +1 -1
  1187. package/dist/magma-components/magma-components.js +1 -1
  1188. package/dist/magma-components/{p-2a445b98.system.entry.js → p-009e4359.system.entry.js} +137 -137
  1189. package/dist/magma-components/{p-b523fabe.system.entry.js → p-01d6d5a5.system.entry.js} +24 -11
  1190. package/dist/magma-components/p-03285704.entry.js +1 -0
  1191. package/dist/magma-components/p-03441f69.entry.js +1 -0
  1192. package/dist/magma-components/p-03896fbd.entry.js +1 -0
  1193. package/dist/magma-components/p-038fc1db.entry.js +1 -0
  1194. package/dist/magma-components/{p-e3b9ea0b.system.entry.js → p-03a2f4e7.system.entry.js} +2 -2
  1195. package/dist/magma-components/{p-4646cdc0.system.entry.js → p-06ba1f71.system.entry.js} +4 -4
  1196. package/dist/magma-components/p-0760e8a4.entry.js +1 -0
  1197. package/dist/magma-components/p-082b787b.entry.js +1 -0
  1198. package/dist/magma-components/p-09537867.entry.js +1 -0
  1199. package/dist/magma-components/p-09675899.entry.js +1 -0
  1200. package/dist/magma-components/p-0a914567.entry.js +1 -0
  1201. package/dist/magma-components/p-0c8dd132.entry.js +1 -0
  1202. package/dist/magma-components/p-0d7370d8.system.entry.js +1 -0
  1203. package/dist/magma-components/p-0e7bb90b.system.entry.js +127 -0
  1204. package/dist/magma-components/{p-03fb86a6.system.entry.js → p-10a68a4d.system.entry.js} +2 -2
  1205. package/dist/magma-components/p-11312b0c.entry.js +1 -0
  1206. package/dist/magma-components/{p-6c73689a.system.entry.js → p-11543f44.system.entry.js} +4 -4
  1207. package/dist/magma-components/{p-e0049e96.system.entry.js → p-11ee7089.system.entry.js} +5 -5
  1208. package/dist/magma-components/p-13e94501.entry.js +1 -0
  1209. package/dist/magma-components/{p-387fa36d.system.entry.js → p-14f60718.system.entry.js} +1 -1
  1210. package/dist/magma-components/p-16651356.entry.js +1 -0
  1211. package/dist/magma-components/p-1686b36a.entry.js +1 -0
  1212. package/dist/magma-components/{p-ad13ade5.system.entry.js → p-16a7e26a.system.entry.js} +4 -4
  1213. package/dist/magma-components/p-1784d5fb.entry.js +1 -0
  1214. package/dist/magma-components/p-18421a84.entry.js +1 -0
  1215. package/dist/magma-components/p-1934151b.entry.js +1 -0
  1216. package/dist/magma-components/p-193b58d0.entry.js +1 -0
  1217. package/dist/magma-components/{p-b30b487c.system.entry.js → p-19f3b524.system.entry.js} +6 -6
  1218. package/dist/magma-components/{p-87831da2.system.entry.js → p-1d101083.system.entry.js} +1 -1
  1219. package/dist/magma-components/p-1db5ab39.entry.js +1 -0
  1220. package/dist/magma-components/{p-fae9612b.system.entry.js → p-1e5d4854.system.entry.js} +7 -7
  1221. package/dist/magma-components/p-1f756317.entry.js +1 -0
  1222. package/dist/magma-components/p-2100343f.entry.js +1 -0
  1223. package/dist/magma-components/p-211b2675.system.entry.js +1 -0
  1224. package/dist/magma-components/{p-445bc62a.system.entry.js → p-2289423c.system.entry.js} +1 -1
  1225. package/dist/magma-components/p-26aad538.entry.js +1 -0
  1226. package/dist/magma-components/p-270e9afa.entry.js +1 -0
  1227. package/dist/magma-components/{p-3b578659.system.entry.js → p-275d7968.system.entry.js} +14 -14
  1228. package/dist/magma-components/{p-f181c679.system.entry.js → p-28ecae1e.system.entry.js} +2 -2
  1229. package/dist/magma-components/{p-9f55fa7a.system.entry.js → p-2a5223df.system.entry.js} +7 -7
  1230. package/dist/magma-components/p-2aa3e73a.system.entry.js +13 -0
  1231. package/dist/magma-components/p-2c64ec7e.entry.js +1 -0
  1232. package/dist/magma-components/{p-05455645.system.entry.js → p-2dc9499c.system.entry.js} +3 -3
  1233. package/dist/magma-components/{p-0384db44.system.entry.js → p-2dd32b3f.system.entry.js} +7 -7
  1234. package/dist/magma-components/p-2e5684a0.system.entry.js +5 -0
  1235. package/dist/magma-components/{p-b0749f83.system.entry.js → p-303173d5.system.entry.js} +3 -3
  1236. package/dist/magma-components/{p-625de2e6.system.entry.js → p-33172d6f.system.entry.js} +8 -5
  1237. package/dist/magma-components/p-333c0ae5.entry.js +1 -0
  1238. package/dist/magma-components/p-3341ac50.entry.js +1 -0
  1239. package/dist/magma-components/p-34183ce3.entry.js +1 -0
  1240. package/dist/magma-components/p-35a77756.entry.js +1 -0
  1241. package/dist/magma-components/p-37172440.entry.js +1 -0
  1242. package/dist/magma-components/p-37470fef.system.entry.js +51 -0
  1243. package/dist/magma-components/p-3b41f929.entry.js +1 -0
  1244. package/dist/magma-components/p-3ccc1c10.entry.js +1 -0
  1245. package/dist/magma-components/p-3d0578a7.entry.js +1 -0
  1246. package/dist/magma-components/p-3d45d7a7.entry.js +1 -0
  1247. package/dist/magma-components/{p-d85f3e5e.system.entry.js → p-3d60f528.system.entry.js} +2 -2
  1248. package/dist/magma-components/p-3fb983e9.system.entry.js +1 -0
  1249. package/dist/magma-components/p-4082973c.system.entry.js +30 -0
  1250. package/dist/magma-components/p-41829c15.system.entry.js +7 -0
  1251. package/dist/magma-components/p-420c5af4.entry.js +1 -0
  1252. package/dist/magma-components/p-4242100c.entry.js +1 -0
  1253. package/dist/magma-components/p-430239ca.entry.js +8 -0
  1254. package/dist/magma-components/p-4564e7ad.entry.js +1 -0
  1255. package/dist/magma-components/{p-a9caed77.entry.js → p-47712df6.entry.js} +1 -1
  1256. package/dist/magma-components/p-478bbfdb.entry.js +1 -0
  1257. package/dist/magma-components/p-478e6930.entry.js +1 -0
  1258. package/dist/magma-components/{p-8b8cd213.system.entry.js → p-483480f9.system.entry.js} +31 -11
  1259. package/dist/magma-components/p-4bb45501.entry.js +1 -0
  1260. package/dist/magma-components/p-4e431466.entry.js +1 -0
  1261. package/dist/magma-components/{p-ae9735e4.system.entry.js → p-4e4dd1c1.system.entry.js} +5 -5
  1262. package/dist/magma-components/{p-109926ce.system.entry.js → p-522968d1.system.entry.js} +6 -6
  1263. package/dist/magma-components/{p-d81fcbde.system.entry.js → p-52b73a95.system.entry.js} +7 -7
  1264. package/dist/magma-components/p-533bb401.system.entry.js +60 -0
  1265. package/dist/magma-components/p-555bd3f8.system.entry.js +29 -0
  1266. package/dist/magma-components/{p-35c170ba.system.entry.js → p-56715bbc.system.entry.js} +4 -4
  1267. package/dist/magma-components/{p-a65ce11a.system.entry.js → p-586878a2.system.entry.js} +2 -2
  1268. package/dist/magma-components/{p-aac622ef.system.entry.js → p-58bbada6.system.entry.js} +1 -1
  1269. package/dist/magma-components/{p-99bfa07e.system.entry.js → p-5b5d57b0.system.entry.js} +4 -4
  1270. package/dist/magma-components/p-5c0f0517.entry.js +1 -0
  1271. package/dist/magma-components/p-5c4aed7e.entry.js +1 -0
  1272. package/dist/magma-components/p-5d8cb375.system.entry.js +107 -0
  1273. package/dist/magma-components/p-62e42a62.entry.js +1 -0
  1274. package/dist/magma-components/p-6443e40f.entry.js +1 -0
  1275. package/dist/magma-components/{p-0c8f22dc.system.entry.js → p-6471c0a4.system.entry.js} +2 -2
  1276. package/dist/magma-components/{p-3be9b384.system.entry.js → p-6619b3c0.system.entry.js} +8 -8
  1277. package/dist/magma-components/p-67fa6fd7.entry.js +1 -0
  1278. package/dist/magma-components/{p-4f48c171.system.entry.js → p-68d83e18.system.entry.js} +1 -1
  1279. package/dist/magma-components/{p-fff26731.system.entry.js → p-6c6ec154.system.entry.js} +4 -4
  1280. package/dist/magma-components/{p-8ac1ba5c.system.entry.js → p-6d7e8240.system.entry.js} +4 -4
  1281. package/dist/magma-components/{p-3f0e6729.system.entry.js → p-6de384d0.system.entry.js} +3 -3
  1282. package/dist/magma-components/p-6fb17347.system.entry.js +1 -0
  1283. package/dist/magma-components/p-6fdf3b37.entry.js +1 -0
  1284. package/dist/magma-components/p-70cf2c28.entry.js +1 -0
  1285. package/dist/magma-components/p-73596a07.entry.js +1 -0
  1286. package/dist/magma-components/{p-1a20f239.system.entry.js → p-73a6ee3b.system.entry.js} +1 -1
  1287. package/dist/magma-components/{p-0a0dfdf4.system.entry.js → p-73b0b35f.system.entry.js} +2 -2
  1288. package/dist/magma-components/p-73c0b53e.system.entry.js +82 -0
  1289. package/dist/magma-components/p-73f22a7d.entry.js +1 -0
  1290. package/dist/magma-components/p-756cd3dc.entry.js +1 -0
  1291. package/dist/magma-components/p-757c3420.entry.js +1 -0
  1292. package/dist/magma-components/p-778a46fa.entry.js +1 -0
  1293. package/dist/magma-components/p-78cced59.entry.js +1 -0
  1294. package/dist/magma-components/p-7caf244b.system.entry.js +7 -0
  1295. package/dist/magma-components/p-7cfa2415.system.entry.js +1 -0
  1296. package/dist/magma-components/p-7e87807d.entry.js +1 -0
  1297. package/dist/magma-components/p-8193fd71.entry.js +1 -0
  1298. package/dist/magma-components/p-82041de2.entry.js +1 -0
  1299. package/dist/magma-components/{p-4669334a.system.entry.js → p-825713bc.system.entry.js} +2 -2
  1300. package/dist/magma-components/p-851010c6.system.entry.js +25 -0
  1301. package/dist/magma-components/p-857e893e.system.entry.js +26 -0
  1302. package/dist/magma-components/p-8928d9b5.system.entry.js +110 -0
  1303. package/dist/magma-components/p-8aa6524e.entry.js +1 -0
  1304. package/dist/magma-components/p-8acbf50a.entry.js +1 -0
  1305. package/dist/magma-components/p-8e471af5.entry.js +1 -0
  1306. package/dist/magma-components/p-913123e6.entry.js +1 -0
  1307. package/dist/magma-components/{p-bc054ffa.system.entry.js → p-91406af1.system.entry.js} +9 -8
  1308. package/dist/magma-components/p-95a29fd2.entry.js +1 -0
  1309. package/dist/magma-components/{p-efe27253.system.entry.js → p-96ece2cc.system.entry.js} +3 -3
  1310. package/dist/magma-components/p-96f66b8f.entry.js +1 -0
  1311. package/dist/magma-components/{p-6129954d.system.entry.js → p-97e55f7e.system.entry.js} +5 -5
  1312. package/dist/magma-components/p-98a3802b.system.entry.js +126 -0
  1313. package/dist/magma-components/{p-18244fd7.system.entry.js → p-9b00051f.system.entry.js} +8 -8
  1314. package/dist/magma-components/p-9be80c34.entry.js +1 -0
  1315. package/dist/magma-components/{p-0fc41e34.system.entry.js → p-9c0d1025.system.entry.js} +1 -1
  1316. package/dist/magma-components/{p-12be0f43.system.entry.js → p-9e3c1c28.system.entry.js} +9 -9
  1317. package/dist/magma-components/{p-BoDvZoCN.system.js → p-B6f9M1Bj.system.js} +8 -1
  1318. package/dist/magma-components/p-B7Jp0tqu.system.js +5 -0
  1319. package/dist/magma-components/p-BAW1DAbr.system.js +13 -0
  1320. package/dist/magma-components/{p-nFkaC8l_.system.js → p-BAcul0Zt.system.js} +1 -1
  1321. package/dist/magma-components/p-BXVzhErg.system.js +12 -0
  1322. package/dist/magma-components/{p-iX3kcwYg.js → p-BXkIXROP.js} +1 -1
  1323. package/dist/magma-components/{p-OafT80hV.js → p-BkfGbFba.js} +2 -2
  1324. package/dist/{components/p-BaFfIZGB.js → magma-components/p-C7p9e0P3.js} +1 -1
  1325. package/dist/magma-components/p-CPibDZjX.js +3 -0
  1326. package/dist/magma-components/{p-CZuIEo2v.system.js → p-CyPLJo0p.system.js} +34 -14
  1327. package/dist/magma-components/{p-CuHZXISO.system.js → p-CzZWts7L.system.js} +18 -18
  1328. package/dist/magma-components/{p-VOjLCGlK.system.js → p-D5Yayq7E.system.js} +47 -5
  1329. package/dist/magma-components/{p-mGgjNqBm.system.js → p-DGfoeZMw.system.js} +19 -9
  1330. package/dist/magma-components/p-DwKxtKwS.js +1 -0
  1331. package/dist/magma-components/{p-BZP13mns.system.js → p-EhfbAdzV.system.js} +52 -51
  1332. package/dist/magma-components/p-H8sVzFTL.js +1 -0
  1333. package/dist/magma-components/p-a00805cd.system.entry.js +136 -0
  1334. package/dist/magma-components/p-a025b35b.entry.js +1 -0
  1335. package/dist/magma-components/p-a02819e3.entry.js +1 -0
  1336. package/dist/magma-components/p-a0389821.entry.js +1 -0
  1337. package/dist/magma-components/p-a075c069.entry.js +1 -0
  1338. package/dist/magma-components/p-a0764f01.entry.js +1 -0
  1339. package/dist/magma-components/{p-3139988c.system.entry.js → p-a171c096.system.entry.js} +4 -4
  1340. package/dist/magma-components/{p-6d009b42.system.entry.js → p-a190c325.system.entry.js} +3 -3
  1341. package/dist/magma-components/{p-8bf8e032.entry.js → p-a33a235e.entry.js} +1 -1
  1342. package/dist/magma-components/{p-45b19935.system.entry.js → p-a4aaf1c6.system.entry.js} +8 -8
  1343. package/dist/magma-components/{p-9ef64212.entry.js → p-a9c7fb3f.entry.js} +3 -3
  1344. package/dist/magma-components/{p-9c2b67fc.system.entry.js → p-a9d100e5.system.entry.js} +6 -6
  1345. package/dist/magma-components/{p-8239e526.system.entry.js → p-aa601247.system.entry.js} +2 -2
  1346. package/dist/magma-components/{p-b781c932.system.entry.js → p-aa86018e.system.entry.js} +2 -2
  1347. package/dist/magma-components/p-ab920e0b.entry.js +1 -0
  1348. package/dist/magma-components/{p-30f95d10.entry.js → p-ac401f1a.entry.js} +1 -1
  1349. package/dist/magma-components/{p-11210b60.system.entry.js → p-ad12fa89.system.entry.js} +3 -3
  1350. package/dist/magma-components/p-ad6b5fc1.system.entry.js +16 -0
  1351. package/dist/magma-components/p-ada93f68.entry.js +1 -0
  1352. package/dist/magma-components/{p-4a72d72c.system.entry.js → p-ae258eca.system.entry.js} +2 -2
  1353. package/dist/magma-components/{p-cfbf3a76.system.entry.js → p-af1a93c6.system.entry.js} +7 -7
  1354. package/dist/magma-components/p-b0406c51.entry.js +1 -0
  1355. package/dist/magma-components/p-b18b0088.system.entry.js +9 -0
  1356. package/dist/magma-components/p-b1fe6261.entry.js +1 -0
  1357. package/dist/magma-components/p-b47c444e.system.entry.js +5 -0
  1358. package/dist/magma-components/p-b4856322.entry.js +1 -0
  1359. package/dist/magma-components/p-b7d90310.entry.js +1 -0
  1360. package/dist/magma-components/{p-b6412ddd.system.entry.js → p-b8e5411d.system.entry.js} +1 -1
  1361. package/dist/magma-components/{p-adab176e.system.entry.js → p-b95f648f.system.entry.js} +3 -3
  1362. package/dist/magma-components/{p-98e167e8.system.entry.js → p-ba148b89.system.entry.js} +7 -7
  1363. package/dist/magma-components/p-bbbf8b89.system.entry.js +29 -0
  1364. package/dist/magma-components/p-bca909d9.entry.js +1 -0
  1365. package/dist/magma-components/p-bd4ad8c7.entry.js +1 -0
  1366. package/dist/magma-components/p-bd539dbc.entry.js +1 -0
  1367. package/dist/magma-components/{p-f7e9af99.system.entry.js → p-c0c69807.system.entry.js} +2 -2
  1368. package/dist/magma-components/{p-22f24125.system.entry.js → p-c2a883b0.system.entry.js} +1 -1
  1369. package/dist/magma-components/p-c2d9cf4e.system.entry.js +1 -0
  1370. package/dist/magma-components/{p-4fd0fdb8.system.entry.js → p-c3cfbc71.system.entry.js} +8 -8
  1371. package/dist/magma-components/p-c5b7f820.system.entry.js +1 -0
  1372. package/dist/magma-components/p-c67655fa.entry.js +1 -0
  1373. package/dist/magma-components/p-c6cab2cb.entry.js +1 -0
  1374. package/dist/magma-components/p-c6f56934.entry.js +1 -0
  1375. package/dist/magma-components/{p-ccffdf0b.system.entry.js → p-c8430552.system.entry.js} +28 -16
  1376. package/dist/magma-components/p-c902d468.entry.js +1 -0
  1377. package/dist/magma-components/p-ca0f3549.entry.js +1 -0
  1378. package/dist/magma-components/{p-9e07535e.system.entry.js → p-ca5867f5.system.entry.js} +27 -14
  1379. package/dist/magma-components/p-cc5518b1.entry.js +1 -0
  1380. package/dist/magma-components/{p-d360e4c5.entry.js → p-ccb23b6a.entry.js} +1 -1
  1381. package/dist/magma-components/p-ccb64689.system.entry.js +113 -0
  1382. package/dist/magma-components/p-cf8cfcac.system.entry.js +10 -0
  1383. package/dist/magma-components/p-cfb153b8.entry.js +1 -0
  1384. package/dist/magma-components/p-cfcb8bb5.entry.js +1 -0
  1385. package/dist/magma-components/p-d0b45a54.entry.js +1 -0
  1386. package/dist/magma-components/{p-90d50492.system.entry.js → p-d0dfa8b5.system.entry.js} +2 -2
  1387. package/dist/magma-components/p-d1281855.system.entry.js +330 -0
  1388. package/dist/magma-components/{p-8a8cad6c.system.entry.js → p-d173ae2f.system.entry.js} +1 -1
  1389. package/dist/magma-components/p-d1751ff6.entry.js +1 -0
  1390. package/dist/magma-components/p-d32ca6ce.entry.js +1 -0
  1391. package/dist/magma-components/p-d4452e41.entry.js +1 -0
  1392. package/dist/magma-components/p-d5dec64d.entry.js +1 -0
  1393. package/dist/magma-components/p-d7813f9b.system.entry.js +13 -0
  1394. package/dist/magma-components/{p-c35ea44d.system.entry.js → p-dd4b04ed.system.entry.js} +3 -3
  1395. package/dist/magma-components/p-ddc31c50.entry.js +1 -0
  1396. package/dist/magma-components/{p-4748378e.system.entry.js → p-df70af5f.system.entry.js} +39 -39
  1397. package/dist/magma-components/p-e009c632.entry.js +1 -0
  1398. package/dist/magma-components/p-e160e4e1.entry.js +1 -0
  1399. package/dist/magma-components/p-e497f0db.entry.js +1 -0
  1400. package/dist/magma-components/p-e4db9ad2.entry.js +1 -0
  1401. package/dist/magma-components/p-e63c1ba4.entry.js +1 -0
  1402. package/dist/magma-components/p-e66db408.entry.js +1 -0
  1403. package/dist/magma-components/{p-f09f3fe1.system.entry.js → p-e84361ee.system.entry.js} +12 -3
  1404. package/dist/magma-components/p-ea93721d.entry.js +1 -0
  1405. package/dist/magma-components/p-eb4f76d8.system.entry.js +22 -0
  1406. package/dist/magma-components/p-ecf29ffa.entry.js +1 -0
  1407. package/dist/magma-components/{p-bba4f1f0.system.entry.js → p-ede31d27.system.entry.js} +11 -11
  1408. package/dist/magma-components/{p-cf42d6ea.system.entry.js → p-ee247029.system.entry.js} +3 -3
  1409. package/dist/magma-components/{p-c915fba5.system.entry.js → p-ee65f0eb.system.entry.js} +5 -5
  1410. package/dist/magma-components/p-efcd8a1d.entry.js +1 -0
  1411. package/dist/magma-components/{p-f40e3918.system.entry.js → p-f01e7a7e.system.entry.js} +4 -4
  1412. package/dist/magma-components/{p-95ddc950.system.entry.js → p-f0d93b22.system.entry.js} +9 -6
  1413. package/dist/magma-components/{p-60acbc5f.system.entry.js → p-f2e5a2c7.system.entry.js} +7 -7
  1414. package/dist/magma-components/p-f3041712.entry.js +1 -0
  1415. package/dist/magma-components/{p-9303fb16.system.entry.js → p-f3f1da06.system.entry.js} +5 -5
  1416. package/dist/magma-components/{p-e79eb427.system.entry.js → p-f4e8f507.system.entry.js} +2 -2
  1417. package/dist/magma-components/{p-384d93dc.system.entry.js → p-f5c82548.system.entry.js} +1 -1
  1418. package/dist/magma-components/p-f6f6d914.system.entry.js +14 -0
  1419. package/dist/magma-components/p-f9d2316a.entry.js +1 -0
  1420. package/dist/magma-components/p-fe4ae251.entry.js +1 -0
  1421. package/dist/magma-components/{p-f4fc9f29.system.entry.js → p-ffcfa9e3.system.entry.js} +2 -2
  1422. package/dist/magma-components/p-kW8cjKIa.js +1 -0
  1423. package/dist/{lint/mcp → mcp}/checks.js +5 -5
  1424. package/dist/{lint/mcp → mcp}/components.js +4 -6
  1425. package/dist/{lint/mcp → mcp}/guides.js +11 -9
  1426. package/dist/{lint/mcp → mcp}/icons.js +21 -0
  1427. package/dist/mcp/package.json +3 -0
  1428. package/dist/{lint/mcp → mcp}/patterns.js +8 -9
  1429. package/dist/{lint/mcp → mcp}/protocol.js +1 -1
  1430. package/dist/{lint/mcp → mcp}/render.js +61 -33
  1431. package/dist/{lint/mcp → mcp}/server.js +4 -4
  1432. package/dist/{lint/mcp → mcp}/tokens.js +1 -2
  1433. package/dist/mcp/tools.json +1374 -0
  1434. package/dist/stats.json +4506 -3454
  1435. package/dist/types/common/aria.d.ts +8 -1
  1436. package/dist/types/common/floating-controller.d.ts +14 -0
  1437. package/dist/types/common/navigation.d.ts +7 -0
  1438. package/dist/types/common/preference.d.ts +26 -2
  1439. package/dist/types/common/validity/index.d.ts +1 -1
  1440. package/dist/types/components/mds-accordion-item/mds-accordion-item.d.ts +10 -2
  1441. package/dist/types/components/mds-accordion-timer-item/mds-accordion-timer-item.d.ts +10 -2
  1442. package/dist/types/components/mds-banner/mds-banner.d.ts +13 -4
  1443. package/dist/types/components/mds-banner/meta/dictionary.d.ts +7 -0
  1444. package/dist/types/components/mds-banner/meta/types.d.ts +2 -0
  1445. package/dist/types/components/mds-button/mds-button.d.ts +50 -4
  1446. package/dist/types/components/mds-button-dropdown/mds-button-dropdown.d.ts +22 -2
  1447. package/dist/types/components/mds-calendar/mds-calendar.d.ts +60 -16
  1448. package/dist/types/components/mds-calendar/meta/types.d.ts +2 -0
  1449. package/dist/types/components/mds-chip/mds-chip.d.ts +10 -0
  1450. package/dist/types/components/mds-dropdown/mds-dropdown.d.ts +1 -0
  1451. package/dist/types/components/mds-icon/services/icons-set.service.d.ts +42 -0
  1452. package/dist/types/components/mds-input/mds-input.d.ts +114 -10
  1453. package/dist/types/components/mds-input/meta/color.d.ts +13 -0
  1454. package/dist/types/components/mds-input/meta/types.d.ts +1 -1
  1455. package/dist/types/components/mds-input/meta/validators.d.ts +5 -0
  1456. package/dist/types/components/mds-input/meta/validity.d.ts +3 -2
  1457. package/dist/types/components/mds-input-date/mds-input-date.d.ts +13 -2
  1458. package/dist/types/components/mds-input-date-range/mds-input-date-range.d.ts +34 -3
  1459. package/dist/types/components/mds-input-range/mds-input-range.d.ts +96 -4
  1460. package/dist/types/components/mds-input-range/meta/event-detail.d.ts +7 -0
  1461. package/dist/types/components/mds-input-range-value/mds-input-range-value.d.ts +18 -0
  1462. package/dist/types/components/mds-input-tip/mds-input-tip.d.ts +6 -3
  1463. package/dist/types/components/mds-input-tip-item/meta/dictionary.d.ts +1 -1
  1464. package/dist/types/components/mds-modal/mds-modal.d.ts +8 -1
  1465. package/dist/types/components/mds-pref/mds-pref.d.ts +6 -9
  1466. package/dist/types/components/mds-pref-mode/mds-pref-mode.d.ts +16 -5
  1467. package/dist/types/components/mds-pref-theme/mds-pref-theme.d.ts +14 -1
  1468. package/dist/types/components/mds-tab/mds-tab.d.ts +2 -1
  1469. package/dist/types/components/mds-table/mds-table.d.ts +6 -1
  1470. package/dist/types/components/mds-table-header/mds-table-header.d.ts +1 -1
  1471. package/dist/types/components/mds-url-view/mds-url-view.d.ts +0 -3
  1472. package/dist/types/components/mds-zero/mds-zero.d.ts +4 -0
  1473. package/dist/types/components.d.ts +224 -51
  1474. package/dist/types/fixtures/dark-mode.d.ts +7 -0
  1475. package/dist/types/index.d.ts +20 -8
  1476. package/dist/types/stencil-public-runtime.d.ts +1 -1
  1477. package/dist/types/type/button.d.ts +2 -0
  1478. package/dist/types/type/file-types.d.ts +1 -1
  1479. package/dist/types/type/input.d.ts +2 -2
  1480. package/package.json +22 -19
  1481. package/dist/components/p-4LbHmDXv.js +0 -1
  1482. package/dist/components/p-B6AFku7a.js +0 -1
  1483. package/dist/components/p-BwT0RJip.js +0 -1
  1484. package/dist/components/p-COUgBzJ4.js +0 -1
  1485. package/dist/components/p-CP5Qw9_T.js +0 -1
  1486. package/dist/components/p-Cvhn9asj.js +0 -1
  1487. package/dist/components/p-DGhzWuCS.js +0 -1
  1488. package/dist/components/p-DJd8f8dz.js +0 -1
  1489. package/dist/components/p-DTtmr_Y9.js +0 -1
  1490. package/dist/components/p-DW6ie49j.js +0 -1
  1491. package/dist/components/p-DlglisEn.js +0 -1
  1492. package/dist/components/p-FsctOap9.js +0 -1
  1493. package/dist/components/p-G7Udw5H5.js +0 -1
  1494. package/dist/components/p-Ic8cYsgt.js +0 -1
  1495. package/dist/components/p-TZJN-ygm.js +0 -3
  1496. package/dist/components/p-jasGzfhE.js +0 -1
  1497. package/dist/components/p-l0KS6hTQ.js +0 -1
  1498. package/dist/esm-es5/aria-Cvhn9asj.js +0 -6
  1499. package/dist/esm-es5/index-BJVvHlvf.js +0 -10
  1500. package/dist/lint/mcp/checks.d.ts +0 -29
  1501. package/dist/lint/mcp/cli.d.ts +0 -2
  1502. package/dist/lint/mcp/color.d.ts +0 -12
  1503. package/dist/lint/mcp/components.d.ts +0 -5
  1504. package/dist/lint/mcp/context.d.ts +0 -45
  1505. package/dist/lint/mcp/guides.d.ts +0 -3
  1506. package/dist/lint/mcp/icons.d.ts +0 -9
  1507. package/dist/lint/mcp/patterns.d.ts +0 -75
  1508. package/dist/lint/mcp/protocol.d.ts +0 -77
  1509. package/dist/lint/mcp/render-page.d.ts +0 -40
  1510. package/dist/lint/mcp/render.d.ts +0 -130
  1511. package/dist/lint/mcp/server.d.ts +0 -39
  1512. package/dist/lint/mcp/tokens.d.ts +0 -37
  1513. package/dist/magma-components/p-02b106c2.entry.js +0 -1
  1514. package/dist/magma-components/p-0417391b.entry.js +0 -1
  1515. package/dist/magma-components/p-06691ab3.system.entry.js +0 -27
  1516. package/dist/magma-components/p-074d7b75.entry.js +0 -1
  1517. package/dist/magma-components/p-08da465d.entry.js +0 -1
  1518. package/dist/magma-components/p-0d3da482.system.entry.js +0 -1
  1519. package/dist/magma-components/p-0d42ac4a.entry.js +0 -1
  1520. package/dist/magma-components/p-10d52280.entry.js +0 -1
  1521. package/dist/magma-components/p-13cfc01a.entry.js +0 -1
  1522. package/dist/magma-components/p-14122f2d.entry.js +0 -1
  1523. package/dist/magma-components/p-1467ded5.system.entry.js +0 -7
  1524. package/dist/magma-components/p-18b27217.entry.js +0 -1
  1525. package/dist/magma-components/p-198ea5d8.entry.js +0 -1
  1526. package/dist/magma-components/p-1d8485de.system.entry.js +0 -28
  1527. package/dist/magma-components/p-1f746ad1.system.entry.js +0 -82
  1528. package/dist/magma-components/p-2111aa67.system.entry.js +0 -1
  1529. package/dist/magma-components/p-21345ecc.entry.js +0 -1
  1530. package/dist/magma-components/p-25dcbf22.entry.js +0 -1
  1531. package/dist/magma-components/p-27254fbd.entry.js +0 -1
  1532. package/dist/magma-components/p-299dab17.entry.js +0 -1
  1533. package/dist/magma-components/p-29dd6d94.entry.js +0 -1
  1534. package/dist/magma-components/p-2d199db0.system.entry.js +0 -25
  1535. package/dist/magma-components/p-2d2cdf0d.entry.js +0 -1
  1536. package/dist/magma-components/p-2e68180d.system.entry.js +0 -32
  1537. package/dist/magma-components/p-308a4ae5.system.entry.js +0 -1
  1538. package/dist/magma-components/p-34421ef2.system.entry.js +0 -77
  1539. package/dist/magma-components/p-37881115.system.entry.js +0 -14
  1540. package/dist/magma-components/p-3af8a86a.system.entry.js +0 -111
  1541. package/dist/magma-components/p-3b494de7.entry.js +0 -1
  1542. package/dist/magma-components/p-445198a1.entry.js +0 -1
  1543. package/dist/magma-components/p-45a3e7eb.entry.js +0 -1
  1544. package/dist/magma-components/p-4606d11f.entry.js +0 -1
  1545. package/dist/magma-components/p-46a928c3.entry.js +0 -1
  1546. package/dist/magma-components/p-4cd21f19.entry.js +0 -1
  1547. package/dist/magma-components/p-4da1c089.entry.js +0 -1
  1548. package/dist/magma-components/p-4e5b8618.system.entry.js +0 -1
  1549. package/dist/magma-components/p-4e8c5b68.entry.js +0 -1
  1550. package/dist/magma-components/p-4f0153cd.entry.js +0 -1
  1551. package/dist/magma-components/p-4fc0e294.entry.js +0 -1
  1552. package/dist/magma-components/p-52211fa3.entry.js +0 -1
  1553. package/dist/magma-components/p-5575f198.entry.js +0 -1
  1554. package/dist/magma-components/p-5686da49.system.entry.js +0 -13
  1555. package/dist/magma-components/p-56a25ec6.entry.js +0 -1
  1556. package/dist/magma-components/p-57ee6e32.entry.js +0 -1
  1557. package/dist/magma-components/p-5931fdfc.system.entry.js +0 -41
  1558. package/dist/magma-components/p-59aa4994.entry.js +0 -1
  1559. package/dist/magma-components/p-5a8fa2d0.entry.js +0 -1
  1560. package/dist/magma-components/p-5aa8f150.entry.js +0 -1
  1561. package/dist/magma-components/p-5c8f408e.entry.js +0 -1
  1562. package/dist/magma-components/p-5d1cba9c.system.entry.js +0 -1
  1563. package/dist/magma-components/p-5d56a7cd.system.entry.js +0 -47
  1564. package/dist/magma-components/p-60b21db7.entry.js +0 -1
  1565. package/dist/magma-components/p-60d6e60f.entry.js +0 -1
  1566. package/dist/magma-components/p-61e11cd0.system.entry.js +0 -16
  1567. package/dist/magma-components/p-627c2780.entry.js +0 -1
  1568. package/dist/magma-components/p-6896786e.entry.js +0 -1
  1569. package/dist/magma-components/p-69319301.system.entry.js +0 -10
  1570. package/dist/magma-components/p-6a994dc1.entry.js +0 -1
  1571. package/dist/magma-components/p-72971cf7.system.entry.js +0 -7
  1572. package/dist/magma-components/p-741f8f45.system.entry.js +0 -13
  1573. package/dist/magma-components/p-7837856f.entry.js +0 -1
  1574. package/dist/magma-components/p-797c64f4.system.entry.js +0 -19
  1575. package/dist/magma-components/p-7a920b70.entry.js +0 -1
  1576. package/dist/magma-components/p-7b06b2f2.entry.js +0 -1
  1577. package/dist/magma-components/p-7c055074.entry.js +0 -1
  1578. package/dist/magma-components/p-7c3a7521.entry.js +0 -1
  1579. package/dist/magma-components/p-7d61f442.entry.js +0 -1
  1580. package/dist/magma-components/p-7ee31f2e.entry.js +0 -1
  1581. package/dist/magma-components/p-7f418ae1.entry.js +0 -1
  1582. package/dist/magma-components/p-7ff5552f.entry.js +0 -1
  1583. package/dist/magma-components/p-81212e34.entry.js +0 -1
  1584. package/dist/magma-components/p-81d2582a.entry.js +0 -1
  1585. package/dist/magma-components/p-844bce77.entry.js +0 -1
  1586. package/dist/magma-components/p-84aac233.entry.js +0 -1
  1587. package/dist/magma-components/p-84d0d701.entry.js +0 -1
  1588. package/dist/magma-components/p-85376ff5.entry.js +0 -1
  1589. package/dist/magma-components/p-85bf9c93.entry.js +0 -1
  1590. package/dist/magma-components/p-86f11a5a.entry.js +0 -1
  1591. package/dist/magma-components/p-8aa4cd10.entry.js +0 -1
  1592. package/dist/magma-components/p-8b8a6662.entry.js +0 -1
  1593. package/dist/magma-components/p-8feba226.entry.js +0 -1
  1594. package/dist/magma-components/p-948ecde4.entry.js +0 -8
  1595. package/dist/magma-components/p-97217527.system.entry.js +0 -1
  1596. package/dist/magma-components/p-97c6e10a.entry.js +0 -1
  1597. package/dist/magma-components/p-9a0f8eb1.entry.js +0 -1
  1598. package/dist/magma-components/p-9c784173.entry.js +0 -1
  1599. package/dist/magma-components/p-9e2b1a29.entry.js +0 -1
  1600. package/dist/magma-components/p-9ed54db1.entry.js +0 -1
  1601. package/dist/magma-components/p-9ef0d4e5.system.entry.js +0 -7
  1602. package/dist/magma-components/p-B8zYiZQY.system.js +0 -5
  1603. package/dist/magma-components/p-CLhuNxYQ.js +0 -1
  1604. package/dist/magma-components/p-CvLLN-QH.js +0 -3
  1605. package/dist/magma-components/p-Cvhn9asj.js +0 -1
  1606. package/dist/magma-components/p-CxTugGM9.system.js +0 -10
  1607. package/dist/magma-components/p-Dx_cCOTw.js +0 -1
  1608. package/dist/magma-components/p-a2e3a545.entry.js +0 -1
  1609. package/dist/magma-components/p-a3156523.system.entry.js +0 -98
  1610. package/dist/magma-components/p-a3d09996.entry.js +0 -1
  1611. package/dist/magma-components/p-a8206d9c.entry.js +0 -1
  1612. package/dist/magma-components/p-ac099ed6.entry.js +0 -1
  1613. package/dist/magma-components/p-ac161cb5.entry.js +0 -1
  1614. package/dist/magma-components/p-b0850daa.entry.js +0 -1
  1615. package/dist/magma-components/p-b2763352.entry.js +0 -1
  1616. package/dist/magma-components/p-b464668b.system.entry.js +0 -105
  1617. package/dist/magma-components/p-b61546fd.entry.js +0 -1
  1618. package/dist/magma-components/p-b85f56d7.entry.js +0 -1
  1619. package/dist/magma-components/p-b8f4938a.entry.js +0 -1
  1620. package/dist/magma-components/p-be2ca282.entry.js +0 -1
  1621. package/dist/magma-components/p-bfd95736.entry.js +0 -1
  1622. package/dist/magma-components/p-c0286dc3.system.entry.js +0 -94
  1623. package/dist/magma-components/p-c2758b81.entry.js +0 -1
  1624. package/dist/magma-components/p-c683cd13.entry.js +0 -1
  1625. package/dist/magma-components/p-c7dc17f8.entry.js +0 -1
  1626. package/dist/magma-components/p-c9553777.entry.js +0 -1
  1627. package/dist/magma-components/p-c9bd81c5.system.entry.js +0 -225
  1628. package/dist/magma-components/p-cd6dd836.entry.js +0 -1
  1629. package/dist/magma-components/p-d29c959d.entry.js +0 -1
  1630. package/dist/magma-components/p-d43e2a9a.entry.js +0 -1
  1631. package/dist/magma-components/p-d50d4023.entry.js +0 -1
  1632. package/dist/magma-components/p-dcb5f965.entry.js +0 -1
  1633. package/dist/magma-components/p-ddfb4da3.entry.js +0 -1
  1634. package/dist/magma-components/p-dfab370b.entry.js +0 -1
  1635. package/dist/magma-components/p-e059aaa9.entry.js +0 -1
  1636. package/dist/magma-components/p-e428490d.system.entry.js +0 -5
  1637. package/dist/magma-components/p-e7f717ab.entry.js +0 -1
  1638. package/dist/magma-components/p-e92327a2.entry.js +0 -1
  1639. package/dist/magma-components/p-ecc2893d.system.entry.js +0 -24
  1640. package/dist/magma-components/p-ed4fd7a4.entry.js +0 -1
  1641. package/dist/magma-components/p-ef1bdd44.entry.js +0 -1
  1642. package/dist/magma-components/p-f045b018.entry.js +0 -1
  1643. package/dist/magma-components/p-f22b8091.entry.js +0 -1
  1644. package/dist/magma-components/p-f493fdc3.entry.js +0 -1
  1645. package/dist/magma-components/p-f5d9f625.entry.js +0 -1
  1646. package/dist/magma-components/p-f7426a75.entry.js +0 -1
  1647. package/dist/magma-components/p-fa387b74.system.entry.js +0 -5
  1648. package/dist/magma-components/p-fba648e0.entry.js +0 -1
  1649. package/dist/magma-components/p-fbf563c8.entry.js +0 -1
  1650. package/dist/magma-components/p-fd81c4ef.system.entry.js +0 -29
  1651. package/dist/magma-components/p-fdedc0ba.entry.js +0 -1
  1652. package/dist/magma-components/p-ff65fc97.entry.js +0 -1
  1653. package/dist/magma-components/p-ff82edad.entry.js +0 -1
  1654. package/dist/magma-components/p-sm_-_oFY.system.js +0 -6
  1655. /package/dist/components/{p-Bz1eiKqd.js → p-To9IeLHs.js} +0 -0
  1656. /package/dist/magma-components/{p-Bz1eiKqd.js → p-To9IeLHs.js} +0 -0
  1657. /package/dist/{lint/mcp → mcp}/cli.js +0 -0
  1658. /package/dist/{lint/mcp → mcp}/color.js +0 -0
  1659. /package/dist/{lint/mcp → mcp}/context.js +0 -0
  1660. /package/dist/{lint/mcp → mcp}/icon.svg +0 -0
  1661. /package/dist/{lint/mcp → mcp}/render-page.js +0 -0
@@ -1,8 +1,8 @@
1
1
  {
2
- "timestamp": "2026-11-04T15:13:27",
2
+ "timestamp": "2026-11-12T09:55:22",
3
3
  "compiler": {
4
4
  "name": "@stencil/core",
5
- "version": "4.45.2",
5
+ "version": "4.45.3",
6
6
  "typescriptVersion": "5.8.3"
7
7
  },
8
8
  "components": [
@@ -23,8 +23,8 @@
23
23
  }
24
24
  ],
25
25
  "usage": {
26
- "1. Description": "The `<mds-accordion>` web component is the compound container of the Magma Design System that groups and orchestrates a set of collapsible `<mds-accordion-item>` panels. It acts as the coordination layer that decides which children are selected.\n\n#### Semantic Behavior\n\n- **Compound parent/child**: The default slot accepts only `<mds-accordion-item>` elements.\n- **Single vs. multiple selection**: By default opening one item collapses the others. With `multiple` set, any number of children may stay open at once and selection state is reported as a comma-separated list of indices.\n- **Mandatory selection**: When `disable-close` is set, the user cannot collapse the currently open item by clicking it again - one panel always remains open.\n- **Emitted event**: `mdsAccordionChange` once for every change of the open items, opening and closing alike, carrying the live `children` NodeList and the `selected` index/indices as a string (empty when none is open). A click that `disable-close` turns down changes nothing and emits nothing.\n\n#### Properties & Visual Configurations\n\nThis component has no shared `variant` / `tone` / `size` props; its two booleans control selection semantics rather than appearance.\n\n#### Other behavioral props\n\n- **`multiple`** switches the group from accordion behavior (one panel at a time) to independent toggles, allowing several panels open simultaneously.\n- **`disableClose`** prevents the active panel from being dismissed; set it to force at least one panel to stay expanded at all times.\n\nPer-panel presentation - the visible `label`, the title style `typography`, and the slotted body content - is configured on each `<mds-accordion-item>` child, not on the accordion itself.\n",
27
- "2. Examples": "Correct and idiomatic ways to use the `<mds-accordion>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Accordion\n\nThe canonical form. Place one or more [`mds-accordion-item`](../mds-accordion-item/AGENTS.md) elements as direct children. Each item requires a `label` for its always-visible header.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Informazioni generali\">\n <mds-text>Contenuto della prima sezione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Requisiti tecnici\">\n <mds-text>Contenuto della seconda sezione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Contatti\">\n <mds-text>Contenuto della terza sezione.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Pre-selected Item on Load\n\nSet the `selected` attribute on a child to have that panel start open. Only one item should be pre-selected in single-selection mode (the default).\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Panoramica\" selected>\n <mds-text>Questa sezione e' aperta per impostazione predefinita.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Dettagli\">\n <mds-text>Questa sezione e' chiusa inizialmente.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Multiple Selection Mode\n\nSet `multiple` to allow any number of panels to be open at the same time. The `mdsAccordionChange` event then reports a comma-separated list of open indices.\n\n```html\n<mds-accordion multiple>\n <mds-accordion-item label=\"Documentazione\" selected>\n <mds-text>Scarica la guida utente in formato PDF.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Video tutorial\" selected>\n <mds-text>Guarda i video di formazione nel portale.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"FAQ\">\n <mds-text>Consulta le domande frequenti.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Mandatory Selection (Non-closable)\n\nSet `disable-close` to prevent the open panel from being collapsed. The currently expanded item stays open even when the user clicks its header again - exactly one panel is always visible.\n\n```html\n<mds-accordion disable-close>\n <mds-accordion-item label=\"Passaggio 1 - Dati anagrafici\" selected>\n <mds-text>Inserisci nome, cognome e codice fiscale.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Passaggio 2 - Residenza\">\n <mds-text>Inserisci indirizzo e comune di residenza.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Passaggio 3 - Riepilogo\">\n <mds-text>Verifica i dati inseriti prima di inviare.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### A Title Above, Parts Inside\n\nThe accordion stands under the title of its section, written by its role; each item is a part, whose title is styled as `h6` (`titles/part`): write `typography=\"h6\"` until the default moves from `h5` with the next major (#1218). The label of an item sits inside the button that opens it, so its `typography` is a style, not a level of the outline.\n\n```html\n<mds-text typography=\"section\" tag=\"h2\">Documenti richiesti</mds-text>\n<mds-accordion>\n <mds-accordion-item label=\"Documento di identita'\" typography=\"h6\">\n <mds-text>Carta d'identita' o passaporto in corso di validita'.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Codice fiscale\" typography=\"h6\">\n <mds-text>La tessera sanitaria o il certificato di attribuzione.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Listening to the Change Event\n\nListen for `mdsAccordionChange` to react when the active panel changes. The event detail carries `children` (the full NodeList) and `selected` (a string index or comma-separated indices when `multiple` is set).\n\n```html\n<mds-accordion id=\"faq-accordion\">\n <mds-accordion-item label=\"Cos'e' Magma?\">\n <mds-text>Magma e' il design system di Maggioli.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Come si installa?\">\n <mds-text>Segui le istruzioni nel file README del pacchetto.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n\n<script>\n document.getElementById('faq-accordion').addEventListener('mdsAccordionChange', (event) => {\n console.log('Pannello aperto:', event.detail.selected);\n });\n</script>\n```\n\n#### Rich Slotted Content in Items\n\nThe default slot of each `mds-accordion-item` accepts text, HTML elements, and other Magma components - use this to build complex content panels.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Dettagli del documento\">\n <mds-text typography=\"label\">Nome file</mds-text>\n <mds-text>Relazione_annuale_2024.pdf</mds-text>\n <mds-hr></mds-hr>\n <mds-text typography=\"label\">Dimensione</mds-text>\n <mds-text>2,4 MB</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Azioni disponibili\">\n <mds-button label=\"Scarica\" icon=\"mi/baseline/download\" variant=\"primary\"></mds-button>\n <mds-button label=\"Condividi\" icon=\"mi/baseline/share\" variant=\"primary\" tone=\"outline\"></mds-button>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Styling Customization\n\nStyle the accordion only through its public `--mds-accordion-*` CSS custom properties. The properties cascade into all child `mds-accordion-item` elements from the host.\n\n```css\n.custom-faq mds-accordion {\n --mds-accordion-color: rgb(var(--magma-text-default));\n --mds-accordion-padding-selected: calc(var(--spacing) * 600) 0 calc(var(--spacing) * 800) 0;\n --mds-accordion-padding-unselected: calc(var(--spacing) * 400) 0;\n}\n```\n",
26
+ "1. Description": "The `<mds-accordion>` web component is the compound container of the Magma Design System that groups and orchestrates a set of collapsible `<mds-accordion-item>` panels. It acts as the coordination layer that decides which children are selected.\n\n#### Semantic Behavior\n\n- **Compound parent/child**: The default slot accepts only `<mds-accordion-item>` elements.\n- **Single vs. multiple selection**: By default opening one item collapses the others. With `multiple` set, any number of children may stay open at once and selection state is reported as a comma-separated list of indices.\n- **Mandatory selection**: When `disable-close` is set, the user cannot collapse the currently open item by clicking it again - one panel always remains open.\n- **Emitted event**: `mdsAccordionChange` once for every change of the open items, opening and closing alike, carrying the live `children` NodeList and the `selected` index/indices as a string (empty when none is open). A click that `disable-close` turns down changes nothing and emits nothing.\n\n#### Properties & Visual Configurations\n\nThis component has no shared `variant` / `tone` / `size` props; its two booleans control selection semantics rather than appearance.\n\n#### Other behavioral props\n\n- **`multiple`** switches the group from accordion behavior (one panel at a time) to independent toggles, allowing several panels open simultaneously.\n- **`disableClose`** prevents the active panel from being dismissed; set it to force at least one panel to stay expanded at all times.\n\nPer-panel presentation - the visible `label`, the title style `typography`, the level `tag` of the title in the outline of the page, and the slotted body content - is configured on each `<mds-accordion-item>` child, not on the accordion itself.\n",
27
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-accordion>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Accordion\n\nThe canonical form. Place one or more [`mds-accordion-item`](../mds-accordion-item/AGENTS.md) elements as direct children. Each item requires a `label` for its always-visible header.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Informazioni generali\">\n <mds-text>Contenuto della prima sezione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Requisiti tecnici\">\n <mds-text>Contenuto della seconda sezione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Contatti\">\n <mds-text>Contenuto della terza sezione.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Pre-selected Item on Load\n\nSet the `selected` attribute on a child to have that panel start open. Only one item should be pre-selected in single-selection mode (the default).\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Panoramica\" selected>\n <mds-text>Questa sezione e' aperta per impostazione predefinita.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Dettagli\">\n <mds-text>Questa sezione e' chiusa inizialmente.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Multiple Selection Mode\n\nSet `multiple` to allow any number of panels to be open at the same time. The `mdsAccordionChange` event then reports a comma-separated list of open indices.\n\n```html\n<mds-accordion multiple>\n <mds-accordion-item label=\"Documentazione\" selected>\n <mds-text>Scarica la guida utente in formato PDF.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Video tutorial\" selected>\n <mds-text>Guarda i video di formazione nel portale.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"FAQ\">\n <mds-text>Consulta le domande frequenti.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Mandatory Selection (Non-closable)\n\nSet `disable-close` to prevent the open panel from being collapsed. The currently expanded item stays open even when the user clicks its header again - exactly one panel is always visible.\n\n```html\n<mds-accordion disable-close>\n <mds-accordion-item label=\"Passaggio 1 - Dati anagrafici\" selected>\n <mds-text>Inserisci nome, cognome e codice fiscale.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Passaggio 2 - Residenza\">\n <mds-text>Inserisci indirizzo e comune di residenza.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Passaggio 3 - Riepilogo\">\n <mds-text>Verifica i dati inseriti prima di inviare.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### A Title Above, Parts Inside\n\nThe accordion stands under the title of its section, written by its role; each item is a part, whose title is styled as `h6` (`titles/part`): write `typography=\"h6\"` until the default moves from `h5` with the next major (#1218). `typography` is the style of an item; its `tag` is the level in the outline, one below the title of the section (`h3` under an `h2`), and the heading wraps the button that opens the item, as the Accordion pattern of the WAI-ARIA Authoring Practices does.\n\n```html\n<mds-text typography=\"section\" tag=\"h2\">Documenti richiesti</mds-text>\n<mds-accordion>\n <mds-accordion-item label=\"Documento di identita'\" typography=\"h6\" tag=\"h3\">\n <mds-text>Carta d'identita' o passaporto in corso di validita'.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Codice fiscale\" typography=\"h6\" tag=\"h3\">\n <mds-text>La tessera sanitaria o il certificato di attribuzione.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Listening to the Change Event\n\nListen for `mdsAccordionChange` to react when the active panel changes. The event detail carries `children` (the full NodeList) and `selected` (a string index or comma-separated indices when `multiple` is set).\n\n```html\n<mds-accordion id=\"faq-accordion\">\n <mds-accordion-item label=\"Cos'e' Magma?\">\n <mds-text>Magma e' il design system di Maggioli.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Come si installa?\">\n <mds-text>Segui le istruzioni nel file README del pacchetto.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n\n<script>\n document.getElementById('faq-accordion').addEventListener('mdsAccordionChange', (event) => {\n console.log('Pannello aperto:', event.detail.selected);\n });\n</script>\n```\n\n#### Rich Slotted Content in Items\n\nThe default slot of each `mds-accordion-item` accepts text, HTML elements, and other Magma components - use this to build complex content panels.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Dettagli del documento\">\n <mds-text typography=\"label\">Nome file</mds-text>\n <mds-text>Relazione_annuale_2024.pdf</mds-text>\n <mds-hr></mds-hr>\n <mds-text typography=\"label\">Dimensione</mds-text>\n <mds-text>2,4 MB</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Azioni disponibili\">\n <mds-button label=\"Scarica\" icon=\"mi/baseline/download\" variant=\"primary\"></mds-button>\n <mds-button label=\"Condividi\" icon=\"mi/baseline/share\" variant=\"primary\" tone=\"outline\"></mds-button>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Styling Customization\n\nStyle the accordion only through its public `--mds-accordion-*` CSS custom properties. The properties cascade into all child `mds-accordion-item` elements from the host.\n\n```css\n.custom-faq mds-accordion {\n --mds-accordion-color: rgb(var(--magma-text-default));\n --mds-accordion-padding-selected: calc(var(--spacing) * 600) 0 calc(var(--spacing) * 800) 0;\n --mds-accordion-padding-unselected: calc(var(--spacing) * 400) 0;\n}\n```\n",
28
28
  "3. Mistakes": "Common incorrect uses of `<mds-accordion>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Place Non-Item Children Directly in the Accordion Slot\n\nThe default slot of `<mds-accordion>` is designed exclusively for `<mds-accordion-item>` elements. Placing raw HTML or other components there bypasses the parent's selection coordination and breaks the compound component communication.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion>\n <div>\n <h3>Sezione uno</h3>\n <p>Contenuto della sezione.</p>\n </div>\n</mds-accordion>\n\n<!-- CORRECT -->\n<mds-accordion>\n <mds-accordion-item label=\"Sezione uno\">\n <mds-text>Contenuto della sezione.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Use `mds-accordion-item` Outside `mds-accordion`\n\n`<mds-accordion-item>` is a compound child and relies on the parent to give it an `id` when it has none and to manage selection state. Used standalone it has no coordinator and its `mdsAccordionItemSelect` / `mdsAccordionItemUnselect` events go unanswered.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion-item label=\"Domanda frequente\">\n <mds-text>Risposta alla domanda.</mds-text>\n</mds-accordion-item>\n\n<!-- CORRECT -->\n<mds-accordion>\n <mds-accordion-item label=\"Domanda frequente\">\n <mds-text>Risposta alla domanda.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Listen to Native `click` or `toggle` Instead of `mdsAccordionChange`\n\nA native `click` bubbles up from anywhere inside the accordion, panel content included, and carries no selection state; there is no native `toggle` event on this component. Listen for `mdsAccordionChange`, whose `detail.selected` holds the open index/indices.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion id=\"my-accordion\">\n <mds-accordion-item label=\"Sezione A\">\n <mds-text>Contenuto A.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n<script>\n document.getElementById('my-accordion').addEventListener('click', (e) => {\n // fires on any click, panel content included, and says nothing about the selection\n console.log('clicked');\n });\n</script>\n\n<!-- CORRECT -->\n<mds-accordion id=\"my-accordion\">\n <mds-accordion-item label=\"Sezione A\">\n <mds-text>Contenuto A.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n<script>\n document.getElementById('my-accordion').addEventListener('mdsAccordionChange', (e) => {\n console.log('Selezione corrente:', e.detail.selected);\n });\n</script>\n```\n\n#### Do Not Mix `mds-accordion-item` and `mds-accordion-timer-item`\n\n[`mds-accordion-timer`](../mds-accordion-timer/AGENTS.md) and its child [`mds-accordion-timer-item`](../mds-accordion-timer-item/AGENTS.md) are a separate compound pair. Slotting timer items into a plain accordion (or vice versa) breaks internal event wiring because each parent only listens for its own child's events.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion>\n <mds-accordion-timer-item description=\"Avanzamento automatico\">\n <mds-text>Contenuto con timer.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion>\n\n<!-- CORRECT - use mds-accordion-timer with mds-accordion-timer-item -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Avanzamento automatico\">\n <mds-text>Contenuto con timer.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Do Not Pierce Shadow DOM to Style Internals\n\nThe only supported customization surface is the public `--mds-accordion-*` CSS custom properties and the documented `::part()` names on `mds-accordion-item` (`content`, `icon`, `label`). Targeting undocumented internals via `>>>` or deep class selectors couples code to the Shadow DOM implementation and breaks on minor releases.\n\n```css\n/* INCORRECT */\nmds-accordion >>> .action {\n font-weight: bold;\n}\nmds-accordion-item::part(spinner) {\n display: none;\n}\n\n/* CORRECT */\nmds-accordion {\n --mds-accordion-color: rgb(var(--magma-text-default));\n}\nmds-accordion-item::part(label) {\n font-style: italic;\n}\n```\n"
29
29
  },
30
30
  "props": [
@@ -215,8 +215,8 @@
215
215
  }
216
216
  ],
217
217
  "usage": {
218
- "1. Description": "The `<mds-accordion-item>` web component is a single collapsible panel of the Magma Design System, designed to be slotted inside its parent [`<mds-accordion>`](../mds-accordion/AGENTS.md). It renders a header button paired with an expandable content region; the parent controls which items are open.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-accordion>`; it is not used standalone, and the parent's slot should hold only `mds-accordion-item` elements, not mixed child types.\n- **Parent-driven selection**: Clicking the header requests a toggle, but the authoritative open/closed state is resolved by the parent - in single mode opening one item closes its siblings, while in `multiple` mode each item toggles independently.\n- **Emitted events**: `mdsAccordionItemSelect` on open, `mdsAccordionItemUnselect` on close, and `mdsAccordionItemChange` on any toggle, each carrying `{ id, selected }`.\n- **Default slot**: Holds the collapsible body content (text, HTML, or components).\n\n#### Properties & Visual Configurations\n\n- **`label`** sets the always-visible header text shown whether the item is open or closed.\n- **`selected`** controls whether the panel is expanded; leave it to the parent to manage in coordinated accordions, or set it initially to have a panel start open.\n- **`typography`** picks the title style applied to the header label, defaulting to `h5`. An item is a part of the page, and the title of a part is styled as `h6` (`titles/part` of the design language): write `typography=\"h6\"` until the default moves with the next major (#1218). `action` gives a compact, control-like header. The header is rendered inside a `<button>`, whose content is presentational, so the value is a style only: assistive technology does not announce it as a heading, and the outline of the page comes from the title above the accordion.\n",
219
- "2. Examples": "Correct and idiomatic ways to use the `<mds-accordion-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Accordion\n\nThe canonical form. Place one or more `<mds-accordion-item>` elements as direct children of [`<mds-accordion>`](../mds-accordion/AGENTS.md). Provide `label` for the header text and put the body content in the default slot.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Cos'e' Magma?\">\n <mds-text>Magma e' il design system di Maggioli, basato su web components.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Come si installa?\">\n <mds-text>Importa il loader e chiama defineCustomElements() nell'entry point.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"E' compatibile con React?\">\n <mds-text>Si', usa il pacchetto @maggioli-design-system/magma-react.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Panel Open by Default\n\nSet `selected` on the item you want pre-expanded. The parent does not resolve conflicts on load, so in single mode set it on one item only, unless `multiple` is also set on the parent.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Introduzione\" selected>\n <mds-text>Questa sezione e' aperta per impostazione predefinita.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Prerequisiti\">\n <mds-text>Node.js 18+ e un package manager npm o pnpm.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Multiple Panels Open Simultaneously\n\nAdd `multiple` to `<mds-accordion>` so the user can expand more than one panel at once. Individual items do not change - the parent mode governs the behaviour.\n\n```html\n<mds-accordion multiple>\n <mds-accordion-item label=\"Configurazione di base\">\n <mds-text>Imposta i token di colore e il tema nell'entry point dell'applicazione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Configurazione avanzata\" selected>\n <mds-text>Personalizza i CSS custom properties per adattare il tema al brand.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Integrazione CI/CD\" selected>\n <mds-text>Configura il job di build per generare documentation.json e readme.md.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Non-closable Accordion\n\nSet the parent `disable-close` attribute to prevent the user from collapsing an open panel. An open item then stays open until another item is clicked; with `multiple`, the last open item cannot be closed. Because `disableClose` defaults to `false`, just add the boolean attribute to enable mandatory selection.\n\n```html\n<mds-accordion disable-close>\n <mds-accordion-item label=\"Passo 1 - Installazione\" selected>\n <mds-text>Esegui npm install @maggioli-design-system/magma per aggiungere il pacchetto.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Passo 2 - Configurazione\">\n <mds-text>Importa defineCustomElements e registra i componenti nell'app.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### The Title of an Item Is a Part\n\nAn item is a part of the page, whose title is styled as `h6` (`titles/part`): write `typography=\"h6\"`, until the default moves from `h5` with the next major (#1218). The level in the outline comes from the title of the section that holds the accordion, written by its role; the label sits inside the button that opens the item, so `typography` is a style only. Use `action` for a compact, control-like header.\n\n```html\n<mds-text typography=\"section\" tag=\"h2\">Domande frequenti</mds-text>\n<mds-accordion>\n <mds-accordion-item label=\"Come gestisco gli aggiornamenti?\" typography=\"h6\">\n <mds-text>Ogni release e' documentata nel changelog con note di migrazione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Posso personalizzare i colori?\" typography=\"h6\">\n <mds-text>Si', tramite i CSS custom properties esposti da ogni componente.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Rich Slot Content\n\nThe default slot accepts any HTML or components - not just text. Use it for structured content such as lists, forms, or nested components.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Dettagli del progetto\">\n <mds-text typography=\"h6\">Tecnologie utilizzate</mds-text>\n <mds-list>\n <mds-list-item>StencilJS</mds-list-item>\n <mds-list-item>TypeScript</mds-list-item>\n <mds-list-item>Storybook</mds-list-item>\n </mds-list>\n </mds-accordion-item>\n <mds-accordion-item label=\"Contatti del team\">\n <mds-text>Scrivi a design-system@maggioli.it per supporto tecnico.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Listening to Item Events\n\n`mdsAccordionItemChange` fires on every toggle; `mdsAccordionItemSelect` fires only on open; `mdsAccordionItemUnselect` fires only on close. Use `mdsAccordionItemChange` when you only need to react to any state change, or the specific event when you need to handle open and close differently. The parent overwrites each item's `id` with `item-<index>` on load, and that is the `detail.id`: do not select items by an `id` of your own.\n\n```html\n<mds-accordion id=\"faq\">\n <mds-accordion-item label=\"Domanda frequente 1\">\n <mds-text>Risposta alla prima domanda.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Domanda frequente 2\">\n <mds-text>Risposta alla seconda domanda.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n\n<script>\n document.querySelector('#faq').addEventListener('mdsAccordionItemChange', (e) => {\n console.log('item changed:', e.detail.id, 'selected:', e.detail.selected);\n });\n\n document.querySelector('#faq mds-accordion-item').addEventListener('mdsAccordionItemSelect', (e) => {\n console.log('faq-1 opened');\n });\n</script>\n```\n\n#### Styling Customization\n\nStyle each item only through its public `--mds-accordion-item-*` CSS custom properties. Setting the public `--mds-accordion-*` properties on the parent `<mds-accordion>` propagates to all children via the cascade variables the items consume.\n\n```css\n/* Customize all items via the parent */\nmds-accordion {\n --mds-accordion-padding-selected: calc(var(--spacing) * 600) 0 calc(var(--spacing) * 800) 0;\n --mds-accordion-padding-unselected: calc(var(--spacing) * 400) 0;\n}\n\n/* Or target a single item directly */\n.sidebar mds-accordion-item {\n --mds-accordion-item-color: rgb(var(--magma-text-default));\n}\n```\n",
218
+ "1. Description": "The `<mds-accordion-item>` web component is a single collapsible panel of the Magma Design System, designed to be slotted inside its parent [`<mds-accordion>`](../mds-accordion/AGENTS.md). It renders a header button paired with an expandable content region; the parent controls which items are open.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-accordion>`; it is not used standalone, and the parent's slot should hold only `mds-accordion-item` elements, not mixed child types.\n- **Parent-driven selection**: Clicking the header requests a toggle, but the authoritative open/closed state is resolved by the parent - in single mode opening one item closes its siblings, while in `multiple` mode each item toggles independently.\n- **Emitted events**: `mdsAccordionItemSelect` on open, `mdsAccordionItemUnselect` on close, and `mdsAccordionItemChange` on any toggle, each carrying `{ id, selected }`.\n- **Default slot**: Holds the collapsible body content (text, HTML, or components).\n\n#### Properties & Visual Configurations\n\n- **`label`** sets the always-visible header text shown whether the item is open or closed.\n- **`selected`** controls whether the panel is expanded; leave it to the parent to manage in coordinated accordions, or set it initially to have a panel start open.\n- **`typography`** picks the title style applied to the header label, defaulting to `h5`. An item is a part of the page, and the title of a part is styled as `h6` (`titles/part` of the design language): write `typography=\"h6\"` until the default moves with the next major (#1218). `action` gives a compact, control-like header. The value is a style only: the label is a `<span>` inside the `<button>` that opens the item, whatever its style.\n- **`tag`** puts the title in the outline of the page, at the level of its place: `tag=\"h3\"` under a section titled `h2`. The heading wraps the button, as the Accordion pattern of the WAI-ARIA Authoring Practices does, so whoever navigates by headings reaches each item. Left out, the item is not a heading: the component cannot know its place, and the level of its style (`h6`) would skip the levels in between.\n",
219
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-accordion-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Accordion\n\nThe canonical form. Place one or more `<mds-accordion-item>` elements as direct children of [`<mds-accordion>`](../mds-accordion/AGENTS.md). Provide `label` for the header text and put the body content in the default slot.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Cos'e' Magma?\">\n <mds-text>Magma e' il design system di Maggioli, basato su web components.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Come si installa?\">\n <mds-text>Importa il loader e chiama defineCustomElements() nell'entry point.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"E' compatibile con React?\">\n <mds-text>Si', usa il pacchetto @maggioli-design-system/magma-react.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Panel Open by Default\n\nSet `selected` on the item you want pre-expanded. The parent does not resolve conflicts on load, so in single mode set it on one item only, unless `multiple` is also set on the parent.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Introduzione\" selected>\n <mds-text>Questa sezione e' aperta per impostazione predefinita.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Prerequisiti\">\n <mds-text>Node.js 18+ e un package manager npm o pnpm.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Multiple Panels Open Simultaneously\n\nAdd `multiple` to `<mds-accordion>` so the user can expand more than one panel at once. Individual items do not change - the parent mode governs the behaviour.\n\n```html\n<mds-accordion multiple>\n <mds-accordion-item label=\"Configurazione di base\">\n <mds-text>Imposta i token di colore e il tema nell'entry point dell'applicazione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Configurazione avanzata\" selected>\n <mds-text>Personalizza i CSS custom properties per adattare il tema al brand.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Integrazione CI/CD\" selected>\n <mds-text>Configura il job di build per generare documentation.json e readme.md.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Non-closable Accordion\n\nSet the parent `disable-close` attribute to prevent the user from collapsing an open panel. An open item then stays open until another item is clicked; with `multiple`, the last open item cannot be closed. Because `disableClose` defaults to `false`, just add the boolean attribute to enable mandatory selection.\n\n```html\n<mds-accordion disable-close>\n <mds-accordion-item label=\"Passo 1 - Installazione\" selected>\n <mds-text>Esegui npm install @maggioli-design-system/magma per aggiungere il pacchetto.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Passo 2 - Configurazione\">\n <mds-text>Importa defineCustomElements e registra i componenti nell'app.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### The Title of an Item Is a Part\n\nAn item is a part of the page, whose title is styled as `h6` (`titles/part`): write `typography=\"h6\"`, until the default moves from `h5` with the next major (#1218). `typography` is the style only; `tag` gives the level of the title in the outline, one below the title of the section that holds the accordion (`h3` under an `h2`). Use `action` for a compact, control-like header.\n\n```html\n<mds-text typography=\"section\" tag=\"h2\">Domande frequenti</mds-text>\n<mds-accordion>\n <mds-accordion-item label=\"Come gestisco gli aggiornamenti?\" typography=\"h6\" tag=\"h3\">\n <mds-text>Ogni release e' documentata nel changelog con note di migrazione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Posso personalizzare i colori?\" typography=\"h6\" tag=\"h3\">\n <mds-text>Si', tramite i CSS custom properties esposti da ogni componente.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\nThe heading wraps the button that opens the item, as the Accordion pattern of the WAI-ARIA Authoring Practices does: a screen reader lists the questions among the headings of the page, under Domande frequenti. Left out, `tag` leaves the item a button only, out of the outline; never write the level of the style (`tag=\"h6\"` under an `h2`), which skips the levels in between.\n\n#### Rich Slot Content\n\nThe default slot accepts any HTML or components - not just text. Use it for structured content such as lists, forms, or nested components.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Dettagli del progetto\">\n <mds-text typography=\"h6\">Tecnologie utilizzate</mds-text>\n <mds-list>\n <mds-list-item>StencilJS</mds-list-item>\n <mds-list-item>TypeScript</mds-list-item>\n <mds-list-item>Storybook</mds-list-item>\n </mds-list>\n </mds-accordion-item>\n <mds-accordion-item label=\"Contatti del team\">\n <mds-text>Scrivi a design-system@maggioli.it per supporto tecnico.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Listening to Item Events\n\n`mdsAccordionItemChange` fires on every toggle; `mdsAccordionItemSelect` fires only on open; `mdsAccordionItemUnselect` fires only on close. Use `mdsAccordionItemChange` when you only need to react to any state change, or the specific event when you need to handle open and close differently. The parent overwrites each item's `id` with `item-<index>` on load, and that is the `detail.id`: do not select items by an `id` of your own.\n\n```html\n<mds-accordion id=\"faq\">\n <mds-accordion-item label=\"Domanda frequente 1\">\n <mds-text>Risposta alla prima domanda.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Domanda frequente 2\">\n <mds-text>Risposta alla seconda domanda.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n\n<script>\n document.querySelector('#faq').addEventListener('mdsAccordionItemChange', (e) => {\n console.log('item changed:', e.detail.id, 'selected:', e.detail.selected);\n });\n\n document.querySelector('#faq mds-accordion-item').addEventListener('mdsAccordionItemSelect', (e) => {\n console.log('faq-1 opened');\n });\n</script>\n```\n\n#### Styling Customization\n\nStyle each item only through its public `--mds-accordion-item-*` CSS custom properties. Setting the public `--mds-accordion-*` properties on the parent `<mds-accordion>` propagates to all children via the cascade variables the items consume.\n\n```css\n/* Customize all items via the parent */\nmds-accordion {\n --mds-accordion-padding-selected: calc(var(--spacing) * 600) 0 calc(var(--spacing) * 800) 0;\n --mds-accordion-padding-unselected: calc(var(--spacing) * 400) 0;\n}\n\n/* Or target a single item directly */\n.sidebar mds-accordion-item {\n --mds-accordion-item-color: rgb(var(--magma-text-default));\n}\n```\n",
220
220
  "3. Mistakes": "Common incorrect uses of `<mds-accordion-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `mds-accordion-item` Outside `mds-accordion`\n\nThe item relies on the parent to give it an `id` when it has none, manage sibling state, and emit coordinated change events. Placed standalone it still toggles, but nothing coordinates it, no `mdsAccordionChange` is emitted, and its events carry an empty `id`.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion-item label=\"Sezione autonoma\">\n <mds-text>Contenuto senza accordeon genitore.</mds-text>\n</mds-accordion-item>\n\n<!-- CORRECT -->\n<mds-accordion>\n <mds-accordion-item label=\"Sezione autonoma\">\n <mds-text>Contenuto all'interno del genitore corretto.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Wrap `mds-accordion-item` in Extra Elements\n\nItems are direct children of `mds-accordion` by contract (see [`agents/conventions.md`](../../../../agents/conventions.md)). The parent still finds wrapped items, since it queries every descendant, but the borders of an open item depend on its position among its siblings (`:first-child` / `:last-child`), which a wrapper changes.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion>\n <div class=\"group\">\n <mds-accordion-item label=\"FAQ 1\">\n <mds-text>Risposta alla prima domanda.</mds-text>\n </mds-accordion-item>\n </div>\n</mds-accordion>\n\n<!-- CORRECT -->\n<mds-accordion>\n <mds-accordion-item label=\"FAQ 1\">\n <mds-text>Risposta alla prima domanda.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Set `label` via the Default Slot\n\n`label` is a required prop that renders the header button text, which is also the button's accessible name; the default slot holds only the collapsible body content. Putting header text in the slot places it inside the body region and leaves the required `label` prop empty, breaking both layout and accessibility.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion>\n <mds-accordion-item>\n Dettagli dell'ordine\n </mds-accordion-item>\n</mds-accordion>\n\n<!-- CORRECT -->\n<mds-accordion>\n <mds-accordion-item label=\"Dettagli dell'ordine\">\n <mds-text>Numero ordine: 12345, data: 01/06/2026.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Override Open/Close State by Piercing the Shadow DOM\n\n`selected` is reflected as a host attribute and is writable via JavaScript. Targeting the internal `.content` div or `.icon` element via `>>>` or undocumented class names to show/hide content manually bypasses the coordinated state machine and breaks sibling sync. The documented `content` part styles the panel body; it does not open it. Setting `selected` from JavaScript emits no event and does not close the siblings: in single mode, unset the open item yourself.\n\n```css\n/* INCORRECT */\nmds-accordion-item >>> .content {\n grid-template-rows: 1fr;\n}\n```\n\n```js\n/* CORRECT - toggle via the reflected property */\nconst item = document.querySelector('mds-accordion-item#shipping'); // the id you gave the item\nitem.selected = true;\n```\n\n#### Do Not Listen for Native `click` or `change` Events Instead of the Documented `mds*` Events\n\nA native `click` bubbles up from anywhere inside the item, body content included, and carries no state; there is no native `change` event on this component. The documented events `mdsAccordionItemChange`, `mdsAccordionItemSelect`, and `mdsAccordionItemUnselect` are the designed surface.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion id=\"faq\">\n <mds-accordion-item label=\"Domanda 1\">\n <mds-text>Risposta 1.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n\n<script>\n document.querySelector('#faq mds-accordion-item').addEventListener('click', () => {\n console.log('clicked - also fires for clicks inside the body');\n });\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('#faq mds-accordion-item').addEventListener('mdsAccordionItemChange', (e) => {\n console.log('stato:', e.detail.selected);\n });\n</script>\n```\n\n#### Do Not Use `<details>`/`<summary>` Inside the Slot as a Second Disclosure Layer\n\nThe item already is a styled disclosure widget. Nesting a native `<details>` inside the slot creates redundant expand/collapse semantics, duplicates keyboard interactions, and produces conflicting visual states.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion>\n <mds-accordion-item label=\"Configurazione\">\n <details>\n <summary>Mostra dettagli</summary>\n <p>Parametri avanzati di configurazione.</p>\n </details>\n </mds-accordion-item>\n</mds-accordion>\n\n<!-- CORRECT - put content directly in the slot -->\n<mds-accordion>\n <mds-accordion-item label=\"Configurazione\">\n <mds-text typography=\"h6\">Parametri avanzati</mds-text>\n <mds-text>Descrizione dei parametri di configurazione avanzata.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n"
221
221
  },
222
222
  "props": [
@@ -269,6 +269,60 @@
269
269
  "getter": false,
270
270
  "setter": false
271
271
  },
272
+ {
273
+ "name": "tag",
274
+ "type": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | undefined",
275
+ "complexType": {
276
+ "original": "TypographyHeadingTagType",
277
+ "resolved": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | undefined",
278
+ "references": {
279
+ "TypographyHeadingTagType": {
280
+ "location": "import",
281
+ "path": "@type/text",
282
+ "id": "src/type/text.ts::TypographyHeadingTagType",
283
+ "referenceLocation": "TypographyHeadingTagType"
284
+ }
285
+ }
286
+ },
287
+ "mutable": false,
288
+ "attr": "tag",
289
+ "reflectToAttr": false,
290
+ "docs": "Specifies the heading level of the title, the level of its place in the outline of the\npage (`h3` under a section titled `h2`): the heading wraps the button that opens the item,\nas the Accordion pattern of the WAI-ARIA Authoring Practices does. Left out, the item is\nnot a heading: only the page knows its place, and the level of the style would skip the\nlevels in between",
291
+ "docsTags": [],
292
+ "values": [
293
+ {
294
+ "value": "h1",
295
+ "type": "string"
296
+ },
297
+ {
298
+ "value": "h2",
299
+ "type": "string"
300
+ },
301
+ {
302
+ "value": "h3",
303
+ "type": "string"
304
+ },
305
+ {
306
+ "value": "h4",
307
+ "type": "string"
308
+ },
309
+ {
310
+ "value": "h5",
311
+ "type": "string"
312
+ },
313
+ {
314
+ "value": "h6",
315
+ "type": "string"
316
+ },
317
+ {
318
+ "type": "undefined"
319
+ }
320
+ ],
321
+ "optional": true,
322
+ "required": false,
323
+ "getter": false,
324
+ "setter": false
325
+ },
272
326
  {
273
327
  "name": "typography",
274
328
  "type": "\"action\" | \"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | undefined",
@@ -287,7 +341,7 @@
287
341
  "mutable": false,
288
342
  "attr": "typography",
289
343
  "reflectToAttr": false,
290
- "docs": "Specifies the typography of the title. An item is a part of the page, whose title is\nstyled as `h6` (`titles/part`, #1189): write `h6` until the default moves with the next\nmajor (#1218). The title sits inside the button that opens the item, so this is its style\nonly, never a level of the outline",
344
+ "docs": "Specifies the typography of the title. An item is a part of the page, whose title is\nstyled as `h6` (`titles/part`, #1189): write `h6` until the default moves with the next\nmajor (#1218). It is the style only: the level of the title in the outline is `tag`",
291
345
  "docsTags": [
292
346
  {
293
347
  "name": "default",
@@ -679,8 +733,8 @@
679
733
  }
680
734
  ],
681
735
  "usage": {
682
- "1. Description": "The `<mds-accordion-timer-item>` web component is the single collapsible panel of a timed, auto-advancing accordion, designed to live exclusively inside its parent [`<mds-accordion-timer>`](../mds-accordion-timer/AGENTS.md). It renders a header button paired with a progress bar and a region that reveals the slotted content while the item is selected.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-accordion-timer>`, alongside other `<mds-accordion-timer-item>` siblings. It is not used standalone or mixed with other child types, since the parent drives the rotating timer across the items.\n- **Selection is parent-orchestrated**: `selected` represents the open state, but only one sibling is open at a time - the parent advances selection on the timer or on a user click.\n- **Click reports up**: Clicking the header of a closed item emits `mdsAccordionTimerItemClickSelect`, and the parent opens it, pauses and re-anchors its timer on it. Clicking the open item does nothing: it stays open.\n- **Programmatic selection**: Setting `selected` to `true` emits `mdsAccordionTimerItemSelect`, and the parent restarts the countdown from the beginning of that item. A click reaches `selected` through the parent, so it emits this event as well, which the parent does not take as a second selection.\n- **Hover pauses the countdown**: While selected, pointer enter/leave emit `mdsAccordionTimerItemMouseEnterSelect` / `mdsAccordionTimerItemMouseLeaveSelect`, which the parent uses to pause and resume the timer. These fire only when the item is currently selected.\n\n#### Properties & Visual Configurations\n\n- **`description`** (required): the title text shown on the header in both open and closed states; it also supplies the accessible label of the content region.\n- **`typography`**: picks the title style of the header text, defaulting to `h5`. An item is a part of the page, styled as `h6` (`titles/part` of the design language): write `typography=\"h6\"` until the default moves with the next major (#1218). The header sits inside the button that opens the item, so the value is a style only, never a level of the outline.\n- **`selected`**: marks this item as the open one. You normally set it on a single item to define the initial open panel; thereafter the parent owns it.\n- **`duration`**: an optional per-item override (in ms) for how long this item stays open before the parent auto-advances, overriding the parent's global `duration` for this item only.\n- **`progress`** and **`uuid`** are managed by the parent at runtime; do not set them manually.\n",
683
- "2. Examples": "Correct and idiomatic ways to use the `<mds-accordion-timer-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Timed Accordion\n\nThe canonical form. Always place `<mds-accordion-timer-item>` as a direct child of [`<mds-accordion-timer>`](../mds-accordion-timer/AGENTS.md). Provide a `description` for each item - it becomes the header label and the accessible name for the content region. Mark one item `selected`: without it the timer does not start.\n\n```html\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Introduzione al progetto\" selected>\n <mds-text>Contenuto dell'introduzione al progetto.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Obiettivi principali\">\n <mds-text>Elenco degli obiettivi principali del progetto.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Conclusioni\">\n <mds-text>Riepilogo e prossimi passi.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Setting the Initially Open Item\n\nMark one item `selected` to define which panel is open on load. The parent reads this state at `componentDidLoad` to anchor its timer on that item. Mark at most one item; the parent will enforce exclusive selection after load.\n\n```html\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Fase uno\" selected>\n <mds-text>Descrizione della fase uno.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Fase due\">\n <mds-text>Descrizione della fase due.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Per-Item Duration Override\n\nSet `duration` (in milliseconds) on a single item to give it a different display time than the global `duration` set on the parent. Omit `duration` on items that should use the parent's default.\n\n```html\n<mds-accordion-timer duration=\"5000\">\n <mds-accordion-timer-item description=\"Panoramica rapida\" duration=\"2000\" selected>\n <mds-text>Questa sezione scorre piu velocemente delle altre.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Dettagli tecnici\" duration=\"12000\">\n <mds-text>Questa sezione richiede piu tempo per la lettura.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Contatti\">\n <mds-text>Usa la durata globale di 5000 ms.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### The Title of an Item Is a Part\n\nAn item is a part of the page, whose title is styled as `h6` (`titles/part`): write `typography=\"h6\"`, until the default moves from `h5` with the next major (#1218). The level in the outline comes from the title of the section that holds the accordion, written by its role; the header sits inside the button that opens the item, so `typography` is a style only.\n\n```html\n<mds-text typography=\"section\" tag=\"h2\">Come funziona</mds-text>\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Argomento principale\" typography=\"h6\">\n <mds-text>Contenuto dell'argomento principale.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Sotto-argomento\" typography=\"h6\">\n <mds-text>Approfondimento del sotto-argomento.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Rich Slotted Content\n\nThe default slot accepts HTML elements and components, not only plain text. Use it to compose images, lists, or nested components inside the disclosure panel.\n\n```html\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Caratteristiche del prodotto\">\n <mds-img src=\"/images/prodotto.jpg\" alt=\"Foto del prodotto\"></mds-img>\n <mds-text>\n Il prodotto include le seguenti funzionalita: gestione utenti, reportistica avanzata e\n integrazione con i sistemi esistenti.\n </mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Prezzi e licenze\">\n <mds-text>Contatta il nostro team commerciale per un preventivo personalizzato.</mds-text>\n <mds-button label=\"Richiedi preventivo\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Reacting to Item Changes\n\nListen for `mdsAccordionTimerItemClickSelect` to detect user-initiated selection (it fires only when a click opens the item). `mdsAccordionTimerItemSelect` on the item fires on every selection - click, code or timer - and `mdsAccordionTimerChange` on the parent reports the new index.\n\n```html\n<mds-accordion-timer id=\"timer\">\n <mds-accordion-timer-item description=\"Notizie in evidenza\" id=\"item-0\" selected>\n <mds-text>Prima notizia in evidenza della giornata.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Aggiornamenti recenti\" id=\"item-1\">\n <mds-text>Ultimi aggiornamenti disponibili.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n\n<script>\n document.getElementById('item-0').addEventListener('mdsAccordionTimerItemClickSelect', (e) => {\n console.log('selezione manuale', e.detail);\n });\n\n document.getElementById('timer').addEventListener('mdsAccordionTimerChange', (e) => {\n console.log('avanzamento automatico, indice:', e.detail.index);\n });\n</script>\n```\n\n#### Styling Customization\n\nStyle the item only through its public `--mds-accordion-timer-item-*` CSS custom properties. Use semantic color roles wrapped in `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working. Note that `--mds-accordion-timer-item-color` is also inherited from the parent's `--mds-accordion-timer-color` counterpart - setting it on the parent applies to all items at once.\n\n```css\n/* Customise a single item by targeting its host */\n.featured-section mds-accordion-timer-item {\n --mds-accordion-timer-item-color: rgb(var(--magma-accent-fg));\n}\n```\n",
736
+ "1. Description": "The `<mds-accordion-timer-item>` web component is the single collapsible panel of a timed, auto-advancing accordion, designed to live exclusively inside its parent [`<mds-accordion-timer>`](../mds-accordion-timer/AGENTS.md). It renders a header button paired with a progress bar and a region that reveals the slotted content while the item is selected.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-accordion-timer>`, alongside other `<mds-accordion-timer-item>` siblings. It is not used standalone or mixed with other child types, since the parent drives the rotating timer across the items.\n- **Selection is parent-orchestrated**: `selected` represents the open state, but only one sibling is open at a time - the parent advances selection on the timer or on a user click.\n- **Click reports up**: Clicking the header of a closed item emits `mdsAccordionTimerItemClickSelect`, and the parent opens it, pauses and re-anchors its timer on it. Clicking the open item does nothing: it stays open.\n- **Programmatic selection**: Setting `selected` to `true` emits `mdsAccordionTimerItemSelect`, and the parent restarts the countdown from the beginning of that item. A click reaches `selected` through the parent, so it emits this event as well, which the parent does not take as a second selection.\n- **Hover pauses the countdown**: While selected, pointer enter/leave emit `mdsAccordionTimerItemMouseEnterSelect` / `mdsAccordionTimerItemMouseLeaveSelect`, which the parent uses to pause and resume the timer. These fire only when the item is currently selected.\n\n#### Properties & Visual Configurations\n\n- **`description`** (required): the title text shown on the header in both open and closed states; it also supplies the accessible label of the content region.\n- **`typography`**: picks the title style of the header text, defaulting to `h5`. An item is a part of the page, styled as `h6` (`titles/part` of the design language): write `typography=\"h6\"` until the default moves with the next major (#1218). The value is a style only: the header is a `<span>` inside the `<button>` that opens the item, whatever its style.\n- **`tag`**: puts the title in the outline of the page, at the level of its place: `tag=\"h3\"` under a section titled `h2`. The heading wraps the button, as the Accordion pattern of the WAI-ARIA Authoring Practices does. Left out, the item is not a heading: the component cannot know its place, and the level of its style (`h6`) would skip the levels in between.\n- **`selected`**: marks this item as the open one. You normally set it on a single item to define the initial open panel; thereafter the parent owns it.\n- **`duration`**: an optional per-item override (in ms) for how long this item stays open before the parent auto-advances, overriding the parent's global `duration` for this item only.\n- **`progress`** and **`uuid`** are managed by the parent at runtime; do not set them manually.\n",
737
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-accordion-timer-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Timed Accordion\n\nThe canonical form. Always place `<mds-accordion-timer-item>` as a direct child of [`<mds-accordion-timer>`](../mds-accordion-timer/AGENTS.md). Provide a `description` for each item - it becomes the header label and the accessible name for the content region. Mark one item `selected`: without it the timer does not start.\n\n```html\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Introduzione al progetto\" selected>\n <mds-text>Contenuto dell'introduzione al progetto.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Obiettivi principali\">\n <mds-text>Elenco degli obiettivi principali del progetto.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Conclusioni\">\n <mds-text>Riepilogo e prossimi passi.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Setting the Initially Open Item\n\nMark one item `selected` to define which panel is open on load. The parent reads this state at `componentDidLoad` to anchor its timer on that item. Mark at most one item; the parent will enforce exclusive selection after load.\n\n```html\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Fase uno\" selected>\n <mds-text>Descrizione della fase uno.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Fase due\">\n <mds-text>Descrizione della fase due.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Per-Item Duration Override\n\nSet `duration` (in milliseconds) on a single item to give it a different display time than the global `duration` set on the parent. Omit `duration` on items that should use the parent's default.\n\n```html\n<mds-accordion-timer duration=\"5000\">\n <mds-accordion-timer-item description=\"Panoramica rapida\" duration=\"2000\" selected>\n <mds-text>Questa sezione scorre piu velocemente delle altre.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Dettagli tecnici\" duration=\"12000\">\n <mds-text>Questa sezione richiede piu tempo per la lettura.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Contatti\">\n <mds-text>Usa la durata globale di 5000 ms.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### The Title of an Item Is a Part\n\nAn item is a part of the page, whose title is styled as `h6` (`titles/part`): write `typography=\"h6\"`, until the default moves from `h5` with the next major (#1218). `typography` is the style only; `tag` gives the level of the title in the outline, one below the title of the section that holds the accordion (`h3` under an `h2`).\n\n```html\n<mds-text typography=\"section\" tag=\"h2\">Come funziona</mds-text>\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Argomento principale\" typography=\"h6\" tag=\"h3\">\n <mds-text>Contenuto dell'argomento principale.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Sotto-argomento\" typography=\"h6\" tag=\"h3\">\n <mds-text>Approfondimento del sotto-argomento.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\nThe heading wraps the button that opens the item, as the Accordion pattern of the WAI-ARIA Authoring Practices does. Left out, `tag` leaves the item a button only, out of the outline; never write the level of the style (`tag=\"h6\"` under an `h2`), which skips the levels in between.\n\n#### Rich Slotted Content\n\nThe default slot accepts HTML elements and components, not only plain text. Use it to compose images, lists, or nested components inside the disclosure panel.\n\n```html\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Caratteristiche del prodotto\">\n <mds-img src=\"/images/prodotto.jpg\" alt=\"Foto del prodotto\"></mds-img>\n <mds-text>\n Il prodotto include le seguenti funzionalita: gestione utenti, reportistica avanzata e\n integrazione con i sistemi esistenti.\n </mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Prezzi e licenze\">\n <mds-text>Contatta il nostro team commerciale per un preventivo personalizzato.</mds-text>\n <mds-button label=\"Richiedi preventivo\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Reacting to Item Changes\n\nListen for `mdsAccordionTimerItemClickSelect` to detect user-initiated selection (it fires only when a click opens the item). `mdsAccordionTimerItemSelect` on the item fires on every selection - click, code or timer - and `mdsAccordionTimerChange` on the parent reports the new index.\n\n```html\n<mds-accordion-timer id=\"timer\">\n <mds-accordion-timer-item description=\"Notizie in evidenza\" id=\"item-0\" selected>\n <mds-text>Prima notizia in evidenza della giornata.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Aggiornamenti recenti\" id=\"item-1\">\n <mds-text>Ultimi aggiornamenti disponibili.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n\n<script>\n document.getElementById('item-0').addEventListener('mdsAccordionTimerItemClickSelect', (e) => {\n console.log('selezione manuale', e.detail);\n });\n\n document.getElementById('timer').addEventListener('mdsAccordionTimerChange', (e) => {\n console.log('avanzamento automatico, indice:', e.detail.index);\n });\n</script>\n```\n\n#### Styling Customization\n\nStyle the item only through its public `--mds-accordion-timer-item-*` CSS custom properties. Use semantic color roles wrapped in `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working. Note that `--mds-accordion-timer-item-color` is also inherited from the parent's `--mds-accordion-timer-color` counterpart - setting it on the parent applies to all items at once.\n\n```css\n/* Customise a single item by targeting its host */\n.featured-section mds-accordion-timer-item {\n --mds-accordion-timer-item-color: rgb(var(--magma-accent-fg));\n}\n```\n",
684
738
  "3. Mistakes": "Common incorrect uses of `<mds-accordion-timer-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use the Item Outside Its Parent\n\n`<mds-accordion-timer-item>` is a compound child and relies on [`<mds-accordion-timer>`](../mds-accordion-timer/AGENTS.md) to assign `uuid`, write `progress`, and drive selection. Standalone use produces a static, non-advancing disclosure with no progress bar updates.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion-timer-item description=\"Dettagli\">\n <mds-text>Contenuto.</mds-text>\n</mds-accordion-timer-item>\n\n<!-- CORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Dettagli\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Do Not Mix with `mds-accordion-item`\n\n`<mds-accordion-timer-item>` and [`<mds-accordion-item>`](../mds-accordion-item/AGENTS.md) are siblings in different compound families and must not be placed in the same parent. The timer accordion indexes only `mds-accordion-timer-item` children; a mixed-in `mds-accordion-item` is left out of the rotation and toggles on its own.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion-timer>\n <mds-accordion-item label=\"Primo\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-item>\n <mds-accordion-timer-item description=\"Secondo\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n\n<!-- CORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Primo\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Secondo\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Do Not Set `progress` or `uuid` Manually\n\nBoth props are reserved for the parent's runtime orchestration. Setting them by hand breaks the timer's internal state tracking and produces incorrect progress bar rendering.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Primo\" uuid=\"0\" progress=\"50\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n\n<!-- CORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Primo\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Do Not Mark More Than One Item `selected`\n\nThe parent does not enforce single selection at load: every item marked `selected` renders open, and the last one drives the timer until the first change closes the others.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Primo\" selected>\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Secondo\" selected>\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n\n<!-- CORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Primo\" selected>\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Secondo\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Do Not Pierce Shadow Parts for Styling\n\nThe documented customization surface is the public `--mds-accordion-timer-item-*` CSS custom properties plus the four shadow parts (`content`, `icon`, `label`, `progress`). Targeting undocumented internals couples code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-accordion-timer-item >>> .action {\n font-weight: bold;\n}\nmds-accordion-timer-item::part(spinner) {\n color: red;\n}\n\n/* CORRECT */\nmds-accordion-timer-item {\n --mds-accordion-timer-item-color: rgb(var(--magma-accent-fg));\n}\nmds-accordion-timer-item::part(label) {\n font-weight: 600;\n}\n```\n\n#### Do Not Omit `description`\n\n`description` is a required prop. It is the only text source for the header label and the accessible name of the content region. Omitting it leaves the button unlabelled and fails accessibility audits.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item>\n <mds-text>Contenuto senza titolo.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n\n<!-- CORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Titolo della sezione\">\n <mds-text>Contenuto della sezione.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n"
685
739
  },
686
740
  "props": [
@@ -791,6 +845,60 @@
791
845
  "getter": false,
792
846
  "setter": false
793
847
  },
848
+ {
849
+ "name": "tag",
850
+ "type": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | undefined",
851
+ "complexType": {
852
+ "original": "TypographyHeadingTagType",
853
+ "resolved": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | undefined",
854
+ "references": {
855
+ "TypographyHeadingTagType": {
856
+ "location": "import",
857
+ "path": "@type/text",
858
+ "id": "src/type/text.ts::TypographyHeadingTagType",
859
+ "referenceLocation": "TypographyHeadingTagType"
860
+ }
861
+ }
862
+ },
863
+ "mutable": false,
864
+ "attr": "tag",
865
+ "reflectToAttr": false,
866
+ "docs": "Specifies the heading level of the title, the level of its place in the outline of the\npage (`h3` under a section titled `h2`): the heading wraps the button that opens the item,\nas the Accordion pattern of the WAI-ARIA Authoring Practices does. Left out, the item is\nnot a heading: only the page knows its place, and the level of the style would skip the\nlevels in between",
867
+ "docsTags": [],
868
+ "values": [
869
+ {
870
+ "value": "h1",
871
+ "type": "string"
872
+ },
873
+ {
874
+ "value": "h2",
875
+ "type": "string"
876
+ },
877
+ {
878
+ "value": "h3",
879
+ "type": "string"
880
+ },
881
+ {
882
+ "value": "h4",
883
+ "type": "string"
884
+ },
885
+ {
886
+ "value": "h5",
887
+ "type": "string"
888
+ },
889
+ {
890
+ "value": "h6",
891
+ "type": "string"
892
+ },
893
+ {
894
+ "type": "undefined"
895
+ }
896
+ ],
897
+ "optional": true,
898
+ "required": false,
899
+ "getter": false,
900
+ "setter": false
901
+ },
794
902
  {
795
903
  "name": "typography",
796
904
  "type": "\"action\" | \"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\"",
@@ -809,7 +917,7 @@
809
917
  "mutable": false,
810
918
  "attr": "typography",
811
919
  "reflectToAttr": false,
812
- "docs": "Specifies the typography of the title. An item is a part of the page, whose title is\nstyled as `h6` (`titles/part`, #1189): write `h6` until the default moves with the next\nmajor (#1218). The title sits inside the button that opens the item, so this is its style\nonly, never a level of the outline",
920
+ "docs": "Specifies the typography of the title. An item is a part of the page, whose title is\nstyled as `h6` (`titles/part`, #1189): write `h6` until the default moves with the next\nmajor (#1218). It is the style only: the level of the title in the outline is `tag`",
813
921
  "docsTags": [
814
922
  {
815
923
  "name": "default",
@@ -1029,13 +1137,13 @@
1029
1137
  "states": [],
1030
1138
  "dependents": [],
1031
1139
  "dependencies": [
1032
- "mds-progress",
1033
- "mds-text"
1140
+ "mds-text",
1141
+ "mds-progress"
1034
1142
  ],
1035
1143
  "dependencyGraph": {
1036
1144
  "mds-accordion-timer-item": [
1037
- "mds-progress",
1038
- "mds-text"
1145
+ "mds-text",
1146
+ "mds-progress"
1039
1147
  ],
1040
1148
  "mds-progress": [
1041
1149
  "mds-radial-progress"
@@ -1441,8 +1549,8 @@
1441
1549
  "mds-button"
1442
1550
  ],
1443
1551
  "mds-button": [
1444
- "mds-spinner",
1445
1552
  "mds-icon",
1553
+ "mds-spinner",
1446
1554
  "mds-text"
1447
1555
  ],
1448
1556
  "mds-avatar-stack-item": [
@@ -1654,8 +1762,8 @@
1654
1762
  "mds-button"
1655
1763
  ],
1656
1764
  "mds-button": [
1657
- "mds-spinner",
1658
1765
  "mds-icon",
1766
+ "mds-spinner",
1659
1767
  "mds-text"
1660
1768
  ]
1661
1769
  },
@@ -1970,8 +2078,8 @@
1970
2078
  "mds-button"
1971
2079
  ],
1972
2080
  "mds-button": [
1973
- "mds-spinner",
1974
2081
  "mds-icon",
2082
+ "mds-spinner",
1975
2083
  "mds-text"
1976
2084
  ],
1977
2085
  "mds-avatar-stack": [
@@ -2322,9 +2430,9 @@
2322
2430
  }
2323
2431
  ],
2324
2432
  "usage": {
2325
- "1. Description": "The `<mds-banner>` web component is the Magma Design System surface for contextual, in-page messages - informational notices, status callouts, and alerts - pairing an optional icon, headline, body text, and inline actions inside a single themed box.\n\n#### Semantic Behavior\n\n- **Variant-driven ARIA**: The announcement role is derived from `variant`, not set manually. `error` and `warning` announce assertively (`role=\"alert\"`); `ai`, `info`, `primary`, and `success` announce politely (`role=\"status\"`); `light` and `dark` are decorative and silent.\n- **Headline as label**: When `headline` is set it also becomes the banner's accessible label.\n- **Dismissal**: When `dismissible` is true a close button is rendered; activating it emits `mdsBannerClose` and, if the banner sits inside an `mds-modal`, closes that modal.\n- **Localized close button**: The close button title is localized (el/en/es/it) from the host language.\n- **Action slot**: The `action` region is rendered only when a direct `[slot=\"action\"]` child is present, so banners without actions produce no empty container.\n\n- **The row of actions stacks when the banner is narrow**: under `--magma-container-actions` of its content (380px) every action of the `action` slot takes the full width, in the order of the row, the main action at the bottom (`actions/stacked`).\n- **Fields take the step below**: a neutral banner paints `surface-overlay`, so a field inside it paints `surface-default` (`--magma-field-fill`); a banner of a status with `tone=\"strong\"` paints a tint, and its fields keep `overlay`.\n\n#### Properties & Visual Configurations\n\nThis component uses the shared `variant` / `tone` ladders defined in [`agents/variants.md`](../../../../agents/variants.md); pick the `variant` according to the message's semantic weight, since it also governs the ARIA behavior described above. `tone` is limited to the minimal-box set (`'weak'`, `'strong'`, `'box'`), defaulting to `'weak'`.\n\n#### Other behavioral props\n\n- **`hideCockade`** (default `false`) removes the colored decorative badge wrapping the leading `icon`; set it for a flatter icon presentation.\n- **`icon`** is a Magma icon library slug shown at the top-left, surfaced as decorative.\n- **`dismissible`** shows the close button - choose it for transient or user-acknowledged messages rather than persistent context.\n- **`deletable`** is the old name of `dismissible`, deprecated: the button dismisses the message, it deletes nothing. It still works, and goes in the next major.\n- The **default slot** carries the body text/markup; the **`action` slot** holds inline controls, with `mds-button` the recommended element.\n",
2326
- "2. Examples": "Correct and idiomatic ways to use the `<mds-banner>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Informational Banner\n\nThe baseline usage. Provide `variant=\"info\"` and place the body copy in the default slot. The component derives `role=\"status\"` and `aria-live=\"polite\"` automatically from the variant.\n\n```html\n<mds-banner variant=\"info\">\n <mds-text typography=\"detail\">\n Il sistema e in manutenzione programmata dalle 22:00 alle 23:00.\n </mds-text>\n</mds-banner>\n```\n\n#### Status Variants\n\nPick the variant that matches the message's semantic weight. `error` and `warning` set `role=\"alert\"` with assertive live region; the others use `role=\"status\"` with polite announcement.\n\n```html\n<!-- Esito positivo -->\n<mds-banner variant=\"success\">\n <mds-text typography=\"detail\">Dati salvati correttamente.</mds-text>\n</mds-banner>\n\n<!-- Avviso non bloccante -->\n<mds-banner variant=\"warning\">\n <mds-text typography=\"detail\">La sessione scadra tra 5 minuti.</mds-text>\n</mds-banner>\n\n<!-- Errore bloccante -->\n<mds-banner variant=\"error\">\n <mds-text typography=\"detail\">Impossibile completare l'operazione. Riprovare.</mds-text>\n</mds-banner>\n```\n\n#### Banner with Headline\n\nUse the `headline` prop to add a title above the body text. The headline is also used as the banner's accessible label (`aria-label`).\n\n```html\n<mds-banner variant=\"warning\" headline=\"Licenza in scadenza\">\n <mds-text typography=\"detail\">\n La licenza del servizio scadra tra 7 giorni. Rinnova ora per non interrompere il servizio.\n </mds-text>\n</mds-banner>\n```\n\n#### Banner with Icon\n\nSet `icon` to a Magma icon slug. The icon is decorative (`aria-hidden=\"true\"`). The colored badge wrapping the icon is shown by default; add `hide-cockade` for a flatter look.\n\n```html\n<!-- Con cockade (default) -->\n<mds-banner variant=\"info\" icon=\"mi/baseline/info\" headline=\"Aggiornamento disponibile\">\n <mds-text typography=\"detail\">E disponibile una nuova versione dell'applicazione.</mds-text>\n</mds-banner>\n\n<!-- Senza cockade -->\n<mds-banner variant=\"success\" icon=\"mi/baseline/check-circle\" hide-cockade>\n <mds-text typography=\"detail\">Operazione completata.</mds-text>\n</mds-banner>\n```\n\n#### Dismissible Banner\n\nSet `dismissible` to show a close button. The button emits `mdsBannerClose` when activated. Listen for the event to remove the banner from the DOM or update application state.\n\n```html\n<mds-banner variant=\"info\" dismissible id=\"promo-banner\">\n <mds-text typography=\"detail\">\n Scopri le nuove funzioni premium disponibili nel tuo piano.\n </mds-text>\n</mds-banner>\n\n<script>\n document.querySelector('#promo-banner').addEventListener('mdsBannerClose', () => {\n document.querySelector('#promo-banner').remove();\n });\n</script>\n```\n\n#### Banner with Action Buttons\n\nSlot `<mds-button>` elements with `slot=\"action\"` to add inline controls. The action region is shown only while at least one `[slot=\"action\"]` child is present, and it follows the actions added or removed after the first render. Match the button variant to the banner variant for visual consistency.\n\n```html\n<mds-banner variant=\"warning\" headline=\"Abbonamento scaduto\">\n <mds-text typography=\"detail\">\n La licenza di questo servizio e scaduta. Il servizio continua a funzionare\n ma non puoi utilizzare le funzioni premium.\n </mds-text>\n <mds-button slot=\"action\" variant=\"warning\" tone=\"outline\">Annulla</mds-button>\n <mds-button slot=\"action\" variant=\"warning\" tone=\"strong\">Rinnova abbonamento</mds-button>\n</mds-banner>\n```\n\n#### Tone for Visual Emphasis\n\n`tone` controls emphasis without changing the semantic variant. `strong` paints the status tint on the whole banner, `weak` (default) keeps a neutral raised surface and colours only the icon, and `box` adds a solid box shadow for high-contrast placements. `mds-banner` accepts only `weak`, `strong`, and `box` - not `outline` or `text`.\n\n```html\n<!-- Bassa enfasi (default) -->\n<mds-banner variant=\"error\" tone=\"weak\">\n <mds-text typography=\"detail\">Errore di validazione nei campi del modulo.</mds-text>\n</mds-banner>\n\n<!-- Alta enfasi -->\n<mds-banner variant=\"error\" tone=\"strong\">\n <mds-text typography=\"detail\">Account bloccato per attivita sospetta. Contatta il supporto.</mds-text>\n</mds-banner>\n```\n\n#### Dark and Light Decorative Variants\n\n`variant=\"dark\"` and `variant=\"light\"` are neutral, decorative banners without an ARIA live region (`role=\"presentation\"`). Use them for non-critical UI chrome - announcements or promotional content that does not require immediate attention.\n\n```html\n<mds-banner variant=\"dark\" tone=\"strong\" headline=\"Novita del mese\">\n <mds-text typography=\"detail\">\n Tre nuovi moduli sono stati aggiunti alla piattaforma.\n </mds-text>\n <mds-button slot=\"action\" variant=\"light\" tone=\"text\">Scopri</mds-button>\n</mds-banner>\n```\n\n#### AI Variant\n\nUse `variant=\"ai\"` to mark banners that present AI-generated content or AI-powered suggestions. The variant emits a polite `role=\"status\"` live announcement.\n\n```html\n<mds-banner variant=\"ai\" icon=\"mi/baseline/auto-awesome\" headline=\"Suggerimento IA\">\n <mds-text typography=\"detail\">\n L'analisi ha rilevato tre anomalie nel documento caricato.\n </mds-text>\n <mds-button slot=\"action\" variant=\"ai\" tone=\"outline\">Visualizza dettagli</mds-button>\n</mds-banner>\n```\n\n#### Dismissible Banner inside mds-modal\n\nWhen `dismissible` is set and the banner lives inside an `<mds-modal>`, activating the close button emits `mdsBannerClose` and also closes the modal automatically - no extra JavaScript needed.\n\n```html\n<mds-modal opened>\n <mds-banner variant=\"warning\" dismissible headline=\"Attenzione\">\n <mds-text typography=\"detail\">\n Stai per eliminare tutti i dati. L'azione non e reversibile.\n </mds-text>\n <mds-button slot=\"action\" variant=\"warning\" tone=\"outline\">Annulla</mds-button>\n <mds-button slot=\"action\" variant=\"warning\" tone=\"strong\">Elimina</mds-button>\n </mds-banner>\n</mds-modal>\n```\n\n#### CSS Custom Property Customization\n\nOverride appearance only through the public `--mds-banner-*` custom properties. Set them on the host or a parent selector; use semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.featured-notice mds-banner {\n --mds-banner-background: rgb(var(--magma-accent-emphasis));\n --mds-banner-color: rgb(var(--magma-accent-on-emphasis));\n --mds-banner-radius: var(--magma-radius-sm);\n --mds-banner-shadow: 0 4px 16px rgb(var(--magma-shadow-ink) / 0.15);\n}\n```\n",
2327
- "3. Mistakes": "Common incorrect uses of `<mds-banner>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use an Invalid `tone` Value\n\n`mds-banner.tone` is typed as `ToneMinimalBoxVariantType`, which allows only `weak`, `strong`, and `box`. Values like `outline` or `text` are not accepted: no tone style matches them, so the banner renders as with `strong`, not with the `weak` default.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"info\" tone=\"outline\">\n <mds-text typography=\"detail\">Informazione di sistema.</mds-text>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"info\" tone=\"weak\">\n <mds-text typography=\"detail\">Informazione di sistema.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Override the ARIA Role Manually\n\nThe component derives `role` and `aria-live` from `variant` (`error`/`warning` assertive, others polite) and writes them on the host when it renders, overwriting a manual value. To change the announcement, change the `variant`.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"info\" role=\"alert\" aria-live=\"assertive\">\n <mds-text typography=\"detail\">Aggiornamento disponibile.</mds-text>\n</mds-banner>\n\n<!-- CORRECT - let variant drive the ARIA behavior -->\n<mds-banner variant=\"info\">\n <mds-text typography=\"detail\">Aggiornamento disponibile.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Slot an `mds-button` into the Default Slot to Add Actions\n\nThe `action` named slot is the correct place for inline controls. Placing buttons in the default slot renders them inside the text region, breaks layout, and loses the flex wrapping the action row provides.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"warning\">\n <mds-text typography=\"detail\">La licenza sta per scadere.</mds-text>\n <mds-button variant=\"warning\">Rinnova</mds-button>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"warning\">\n <mds-text typography=\"detail\">La licenza sta per scadere.</mds-text>\n <mds-button slot=\"action\" variant=\"warning\" tone=\"strong\">Rinnova</mds-button>\n</mds-banner>\n```\n\n#### Do Not Set `dismissible=\"false\"` to Hide the Close Button\n\n`dismissible` is a boolean prop, and a false boolean is an absent attribute ([`agents/mistakes.md`](../../../../agents/mistakes.md)). Stencil reads the string `\"false\"` as `false` here, so the button is hidden, but the attribute stays on the element and any `[dismissible]` selector still matches it. Remove the attribute (or omit it) to hide the button.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"error\" dismissible=\"false\">\n <mds-text typography=\"detail\">Errore permanente - non dismissibile.</mds-text>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"error\">\n <mds-text typography=\"detail\">Errore permanente - non dismissibile.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Use `dark` or `light` for Status Messages\n\n`variant=\"dark\"` and `variant=\"light\"` produce `role=\"presentation\"` with no live region - they are silent to assistive tech. Using them for error, warning, or informational content means screen reader users never receive the announcement.\n\n```html\n<!-- INCORRECT - errore silenzioso per tecnologie assistive -->\n<mds-banner variant=\"dark\">\n <mds-text typography=\"detail\">Errore: impossibile caricare il documento.</mds-text>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"error\">\n <mds-text typography=\"detail\">Errore: impossibile caricare il documento.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Pierce Shadow DOM to Style Internals\n\nThe only supported customization surface is the public `--mds-banner-*` CSS custom properties plus the `::part(text)` shadow part. Targeting internal class names with `>>>` or undocumented `::part()` names couples your code to the implementation and breaks on minor releases.\n\n```css\n/* INCORRECT */\nmds-banner >>> .headline {\n font-size: 1.5rem;\n}\nmds-banner::part(content) {\n padding: 0;\n}\n\n/* CORRECT */\nmds-banner {\n --mds-banner-radius: var(--magma-radius-sm);\n}\nmds-banner::part(text) {\n line-height: 1.6;\n}\n```\n\n#### Do Not Listen to the Native `click` Event for Dismissal\n\nThe component fires `mdsBannerClose` only when the close button is activated (both pointer and keyboard). A native `click` listener on the host fires for a click anywhere in the banner, body text and action buttons included.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"info\" dismissible id=\"notice\">\n <mds-text typography=\"detail\">Avviso temporaneo.</mds-text>\n</mds-banner>\n<script>\n document.querySelector('#notice').addEventListener('click', () => {\n document.querySelector('#notice').remove();\n });\n</script>\n\n<!-- CORRECT -->\n<mds-banner variant=\"info\" dismissible id=\"notice\">\n <mds-text typography=\"detail\">Avviso temporaneo.</mds-text>\n</mds-banner>\n<script>\n document.querySelector('#notice').addEventListener('mdsBannerClose', () => {\n document.querySelector('#notice').remove();\n });\n</script>\n```\n"
2433
+ "1. Description": "The `<mds-banner>` web component is the Magma Design System surface for contextual, in-page messages - informational notices, status callouts, and alerts - pairing an optional icon, headline, body text, and inline actions inside a single themed box.\n\n#### Semantic Behavior\n\n- **Variant-driven ARIA**: The announcement role is derived from `variant`, not set manually. `error` and `warning` announce assertively (`role=\"alert\"`); `ai`, `info`, `primary`, and `success` announce politely (`role=\"status\"`); `light` and `dark` are decorative and silent.\n- **Headline as label**: When `headline` is set it also becomes the banner's accessible label.\n- **The headline follows its place**: in the page it is the title of a part, `h6`; as the window of a dialog (`slot=\"window\"` on a child of `mds-modal`) it is the title of the dialog, `h5`, above the `h6` of the parts and the groups of fields the dialog holds (`titles/part` and `titles/dialog` of the design language). A banner moved in or out of a modal after the load, or given the slot `window` there, takes the style of its new place.\n- **Dismissal**: When `dismissible` is true a close button is rendered; activating it emits `mdsBannerClose` and, if the banner sits inside an `mds-modal`, closes that modal.\n- **Localized close button**: The close button title is localized (el/en/es/it) from the host language.\n- **Action slot**: The `action` region is rendered only when a direct `[slot=\"action\"]` child is present, so banners without actions produce no empty container.\n\n- **The row of actions stacks when the banner is narrow**: under `--magma-container-actions` of its content (380px) every action of the `action` slot takes the full width, in the order of the row, the main action at the bottom (`actions/stacked`).\n- **Fields take the step below**: a neutral banner paints `surface-overlay`, so a field inside it paints `surface-default` (`--magma-field-fill`); a banner of a status with `tone=\"strong\"` paints a tint, and its fields keep `overlay`.\n\n#### Properties & Visual Configurations\n\nThis component uses the shared `variant` / `tone` ladders defined in [`agents/variants.md`](../../../../agents/variants.md); pick the `variant` according to the message's semantic weight, since it also governs the ARIA behavior described above. `tone` is limited to the minimal-box set (`'weak'`, `'strong'`, `'box'`), defaulting to `'weak'`.\n\n#### Other behavioral props\n\n- **`hideCockade`** (default `false`) removes the colored decorative badge wrapping the leading `icon`; set it for a flatter icon presentation.\n- **`typography`** writes the style of the headline instead of its place: `h6` or `h5`, nothing larger, since `h4` is too large for a banner. A value it does not know falls back to the style of the place. Left out, the style is the role of the title of the place (`part`, `dialog`), so a theme that moves the role moves the headline too.\n- **`icon`** is a Magma icon library slug shown at the top-left, surfaced as decorative.\n- **`dismissible`** shows the close button - choose it for transient or user-acknowledged messages rather than persistent context.\n- **`deletable`** is the old name of `dismissible`, deprecated: the button dismisses the message, it deletes nothing. It still works, and goes in the next major.\n- The **default slot** carries the body text/markup; the **`action` slot** holds inline controls, with `mds-button` the recommended element.\n",
2434
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-banner>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Informational Banner\n\nThe baseline usage. Provide `variant=\"info\"` and place the body copy in the default slot. The component derives `role=\"status\"` and `aria-live=\"polite\"` automatically from the variant.\n\n```html\n<mds-banner variant=\"info\">\n <mds-text typography=\"detail\">\n Il sistema e in manutenzione programmata dalle 22:00 alle 23:00.\n </mds-text>\n</mds-banner>\n```\n\n#### Status Variants\n\nPick the variant that matches the message's semantic weight. `error` and `warning` set `role=\"alert\"` with assertive live region; the others use `role=\"status\"` with polite announcement.\n\n```html\n<!-- Esito positivo -->\n<mds-banner variant=\"success\">\n <mds-text typography=\"detail\">Dati salvati correttamente.</mds-text>\n</mds-banner>\n\n<!-- Avviso non bloccante -->\n<mds-banner variant=\"warning\">\n <mds-text typography=\"detail\">La sessione scadra tra 5 minuti.</mds-text>\n</mds-banner>\n\n<!-- Errore bloccante -->\n<mds-banner variant=\"error\">\n <mds-text typography=\"detail\">Impossibile completare l'operazione. Riprovare.</mds-text>\n</mds-banner>\n```\n\n#### Banner with Headline\n\nUse the `headline` prop to add a title above the body text. The headline is also used as the banner's accessible label (`aria-label`).\n\n```html\n<mds-banner variant=\"warning\" headline=\"Licenza in scadenza\">\n <mds-text typography=\"detail\">\n La licenza del servizio scadra tra 7 giorni. Rinnova ora per non interrompere il servizio.\n </mds-text>\n</mds-banner>\n```\n\n#### Banner with Icon\n\nSet `icon` to a Magma icon slug. The icon is decorative (`aria-hidden=\"true\"`). The colored badge wrapping the icon is shown by default; add `hide-cockade` for a flatter look.\n\n```html\n<!-- Con cockade (default) -->\n<mds-banner variant=\"info\" icon=\"mi/baseline/info\" headline=\"Aggiornamento disponibile\">\n <mds-text typography=\"detail\">E disponibile una nuova versione dell'applicazione.</mds-text>\n</mds-banner>\n\n<!-- Senza cockade -->\n<mds-banner variant=\"success\" icon=\"mi/baseline/check-circle\" hide-cockade>\n <mds-text typography=\"detail\">Operazione completata.</mds-text>\n</mds-banner>\n```\n\n#### Dismissible Banner\n\nSet `dismissible` to show a close button. The button emits `mdsBannerClose` when activated. Listen for the event to remove the banner from the DOM or update application state.\n\n```html\n<mds-banner variant=\"info\" dismissible id=\"promo-banner\">\n <mds-text typography=\"detail\">\n Scopri le nuove funzioni premium disponibili nel tuo piano.\n </mds-text>\n</mds-banner>\n\n<script>\n document.querySelector('#promo-banner').addEventListener('mdsBannerClose', () => {\n document.querySelector('#promo-banner').remove();\n });\n</script>\n```\n\n#### Banner with Action Buttons\n\nSlot `<mds-button>` elements with `slot=\"action\"` to add inline controls. The action region is shown only while at least one `[slot=\"action\"]` child is present, and it follows the actions added or removed after the first render. Match the button variant to the banner variant for visual consistency.\n\n```html\n<mds-banner variant=\"warning\" headline=\"Abbonamento scaduto\">\n <mds-text typography=\"detail\">\n La licenza di questo servizio e scaduta. Il servizio continua a funzionare\n ma non puoi utilizzare le funzioni premium.\n </mds-text>\n <mds-button slot=\"action\" variant=\"warning\" tone=\"outline\">Annulla</mds-button>\n <mds-button slot=\"action\" variant=\"warning\" tone=\"strong\">Rinnova abbonamento</mds-button>\n</mds-banner>\n```\n\n#### Tone for Visual Emphasis\n\n`tone` controls emphasis without changing the semantic variant. `strong` paints the status tint on the whole banner, `weak` (default) keeps a neutral raised surface and colours only the icon, and `box` adds a solid box shadow for high-contrast placements. `mds-banner` accepts only `weak`, `strong`, and `box` - not `outline` or `text`.\n\n```html\n<!-- Bassa enfasi (default) -->\n<mds-banner variant=\"error\" tone=\"weak\">\n <mds-text typography=\"detail\">Errore di validazione nei campi del modulo.</mds-text>\n</mds-banner>\n\n<!-- Alta enfasi -->\n<mds-banner variant=\"error\" tone=\"strong\">\n <mds-text typography=\"detail\">Account bloccato per attivita sospetta. Contatta il supporto.</mds-text>\n</mds-banner>\n```\n\n#### Dark and Light Decorative Variants\n\n`variant=\"dark\"` and `variant=\"light\"` are neutral, decorative banners without an ARIA live region (`role=\"presentation\"`). Use them for non-critical UI chrome - announcements or promotional content that does not require immediate attention.\n\n```html\n<mds-banner variant=\"dark\" tone=\"strong\" headline=\"Novita del mese\">\n <mds-text typography=\"detail\">\n Tre nuovi moduli sono stati aggiunti alla piattaforma.\n </mds-text>\n <mds-button slot=\"action\" variant=\"light\" tone=\"text\">Scopri</mds-button>\n</mds-banner>\n```\n\n#### AI Variant\n\nUse `variant=\"ai\"` to mark banners that present AI-generated content or AI-powered suggestions. The variant emits a polite `role=\"status\"` live announcement.\n\n```html\n<mds-banner variant=\"ai\" icon=\"mi/baseline/auto-awesome\" headline=\"Suggerimento IA\">\n <mds-text typography=\"detail\">\n L'analisi ha rilevato tre anomalie nel documento caricato.\n </mds-text>\n <mds-button slot=\"action\" variant=\"ai\" tone=\"outline\">Visualizza dettagli</mds-button>\n</mds-banner>\n```\n\n#### The Window of a Dialog\n\nSlotted as the `window` of an `<mds-modal>`, the banner is the dialog: `variant=\"light\"` `tone=\"box\"` `dismissible`, its close button closes the modal with no extra JavaScript, and its headline is the title of the dialog, in `h5`, with no attribute to write. The headline is hidden from screen readers, so `aria-label` on `mds-modal` names the dialog, with the same text.\n\n```html\n<mds-modal aria-label=\"Eliminare Contratto di servizio?\">\n <mds-banner slot=\"window\" variant=\"light\" tone=\"box\" dismissible headline=\"Eliminare Contratto di servizio?\">\n <mds-text typography=\"detail\">Il documento non potra' essere recuperato.</mds-text>\n <mds-button slot=\"action\" variant=\"dark\" tone=\"outline\" autofocus>Annulla</mds-button>\n <mds-button slot=\"action\" variant=\"error\" tone=\"strong\">Elimina</mds-button>\n </mds-banner>\n</mds-modal>\n```\n\nIn the page the same banner keeps its headline in `h6`, the title of a part. `typography` writes the style when the place does not say it: `h6` or `h5`, nothing larger.\n\n```html\n<mds-banner variant=\"info\" typography=\"h5\" headline=\"Nuova versione del servizio\">\n <mds-text typography=\"detail\">Da oggi puoi firmare i documenti dall'app.</mds-text>\n</mds-banner>\n```\n\n#### CSS Custom Property Customization\n\nOverride appearance only through the public `--mds-banner-*` custom properties. Set them on the host or a parent selector; use semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.featured-notice mds-banner {\n --mds-banner-background: rgb(var(--magma-accent-emphasis));\n --mds-banner-color: rgb(var(--magma-accent-on-emphasis));\n --mds-banner-radius: var(--magma-radius-sm);\n --mds-banner-shadow: 0 4px 16px rgb(var(--magma-shadow-ink) / 0.15);\n}\n```\n",
2435
+ "3. Mistakes": "Common incorrect uses of `<mds-banner>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use an Invalid `tone` Value\n\n`mds-banner.tone` is typed as `ToneMinimalBoxVariantType`, which allows only `weak`, `strong`, and `box`. Values like `outline` or `text` are not accepted: no tone style matches them, so the banner renders as with `strong`, not with the `weak` default.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"info\" tone=\"outline\">\n <mds-text typography=\"detail\">Informazione di sistema.</mds-text>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"info\" tone=\"weak\">\n <mds-text typography=\"detail\">Informazione di sistema.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Ask the Headline for a Style Larger Than `h5`\n\n`typography` takes `h6` and `h5` only: a value it does not know, such as `h4`, falls back to the style of the place. A title written in the default slot instead of `headline` is no headline either: it is not the accessible label of the banner, and it keeps its style wherever the banner goes. Write the title in `headline` and leave its style to the place, or write `h6` or `h5`.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"info\" typography=\"h4\" headline=\"Nuovo servizio\">\n <mds-text typography=\"detail\">Da oggi puoi firmare i documenti dall'app.</mds-text>\n</mds-banner>\n<mds-banner variant=\"info\">\n <mds-text typography=\"h4\">Nuovo servizio</mds-text>\n <mds-text typography=\"detail\">Da oggi puoi firmare i documenti dall'app.</mds-text>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"info\" headline=\"Nuovo servizio\">\n <mds-text typography=\"detail\">Da oggi puoi firmare i documenti dall'app.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Override the ARIA Role Manually\n\nThe component derives `role` and `aria-live` from `variant` (`error`/`warning` assertive, others polite) and writes them on the host when it renders, overwriting a manual value. To change the announcement, change the `variant`.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"info\" role=\"alert\" aria-live=\"assertive\">\n <mds-text typography=\"detail\">Aggiornamento disponibile.</mds-text>\n</mds-banner>\n\n<!-- CORRECT - let variant drive the ARIA behavior -->\n<mds-banner variant=\"info\">\n <mds-text typography=\"detail\">Aggiornamento disponibile.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Slot an `mds-button` into the Default Slot to Add Actions\n\nThe `action` named slot is the correct place for inline controls. Placing buttons in the default slot renders them inside the text region, breaks layout, and loses the flex wrapping the action row provides.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"warning\">\n <mds-text typography=\"detail\">La licenza sta per scadere.</mds-text>\n <mds-button variant=\"warning\">Rinnova</mds-button>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"warning\">\n <mds-text typography=\"detail\">La licenza sta per scadere.</mds-text>\n <mds-button slot=\"action\" variant=\"warning\" tone=\"strong\">Rinnova</mds-button>\n</mds-banner>\n```\n\n#### Do Not Set `dismissible=\"false\"` to Hide the Close Button\n\n`dismissible` is a boolean prop, and a false boolean is an absent attribute ([`agents/mistakes.md`](../../../../agents/mistakes.md)). Stencil reads the string `\"false\"` as `false` here, so the button is hidden, but the attribute stays on the element and any `[dismissible]` selector still matches it. Remove the attribute (or omit it) to hide the button.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"error\" dismissible=\"false\">\n <mds-text typography=\"detail\">Errore permanente - non dismissibile.</mds-text>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"error\">\n <mds-text typography=\"detail\">Errore permanente - non dismissibile.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Use `dark` or `light` for Status Messages\n\n`variant=\"dark\"` and `variant=\"light\"` produce `role=\"presentation\"` with no live region - they are silent to assistive tech. Using them for error, warning, or informational content means screen reader users never receive the announcement.\n\n```html\n<!-- INCORRECT - errore silenzioso per tecnologie assistive -->\n<mds-banner variant=\"dark\">\n <mds-text typography=\"detail\">Errore: impossibile caricare il documento.</mds-text>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"error\">\n <mds-text typography=\"detail\">Errore: impossibile caricare il documento.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Pierce Shadow DOM to Style Internals\n\nThe only supported customization surface is the public `--mds-banner-*` CSS custom properties plus the `::part(text)` shadow part. Targeting internal class names with `>>>` or undocumented `::part()` names couples your code to the implementation and breaks on minor releases.\n\n```css\n/* INCORRECT */\nmds-banner >>> .headline {\n font-size: 1.5rem;\n}\nmds-banner::part(content) {\n padding: 0;\n}\n\n/* CORRECT */\nmds-banner {\n --mds-banner-radius: var(--magma-radius-sm);\n}\nmds-banner::part(text) {\n line-height: 1.6;\n}\n```\n\n#### Do Not Listen to the Native `click` Event for Dismissal\n\nThe component fires `mdsBannerClose` only when the close button is activated (both pointer and keyboard). A native `click` listener on the host fires for a click anywhere in the banner, body text and action buttons included.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"info\" dismissible id=\"notice\">\n <mds-text typography=\"detail\">Avviso temporaneo.</mds-text>\n</mds-banner>\n<script>\n document.querySelector('#notice').addEventListener('click', () => {\n document.querySelector('#notice').remove();\n });\n</script>\n\n<!-- CORRECT -->\n<mds-banner variant=\"info\" dismissible id=\"notice\">\n <mds-text typography=\"detail\">Avviso temporaneo.</mds-text>\n</mds-banner>\n<script>\n document.querySelector('#notice').addEventListener('mdsBannerClose', () => {\n document.querySelector('#notice').remove();\n });\n</script>\n```\n"
2328
2436
  },
2329
2437
  "props": [
2330
2438
  {
@@ -2517,6 +2625,44 @@
2517
2625
  "getter": false,
2518
2626
  "setter": false
2519
2627
  },
2628
+ {
2629
+ "name": "typography",
2630
+ "type": "\"h5\" | \"h6\" | undefined",
2631
+ "complexType": {
2632
+ "original": "BannerTypographyType",
2633
+ "resolved": "\"h5\" | \"h6\" | undefined",
2634
+ "references": {
2635
+ "BannerTypographyType": {
2636
+ "location": "import",
2637
+ "path": "./meta/types",
2638
+ "id": "src/components/mds-banner/meta/types.ts::BannerTypographyType",
2639
+ "referenceLocation": "BannerTypographyType"
2640
+ }
2641
+ }
2642
+ },
2643
+ "mutable": false,
2644
+ "attr": "typography",
2645
+ "reflectToAttr": false,
2646
+ "docs": "The style of the headline: `h6`, the title of a part, or `h5`, the title of a dialog\n(#1189, titles). Left out, it follows the place of the banner: `h6` in the page, `h5` as\nthe window of a dialog (`slot=\"window\"` on a child of `mds-modal`), above the `h6` of the\nparts and the groups of fields it holds. Nothing larger: `h4` is too large for a banner",
2647
+ "docsTags": [],
2648
+ "values": [
2649
+ {
2650
+ "value": "h5",
2651
+ "type": "string"
2652
+ },
2653
+ {
2654
+ "value": "h6",
2655
+ "type": "string"
2656
+ },
2657
+ {
2658
+ "type": "undefined"
2659
+ }
2660
+ ],
2661
+ "optional": true,
2662
+ "required": false,
2663
+ "getter": false,
2664
+ "setter": false
2665
+ },
2520
2666
  {
2521
2667
  "name": "variant",
2522
2668
  "type": "\"ai\" | \"dark\" | \"error\" | \"info\" | \"light\" | \"primary\" | \"success\" | \"warning\" | undefined",
@@ -2704,8 +2850,8 @@
2704
2850
  "mds-button"
2705
2851
  ],
2706
2852
  "mds-button": [
2707
- "mds-spinner",
2708
2853
  "mds-icon",
2854
+ "mds-spinner",
2709
2855
  "mds-text"
2710
2856
  ],
2711
2857
  "mds-policy-ai": [
@@ -4120,8 +4266,8 @@
4120
4266
  "mds-button"
4121
4267
  ],
4122
4268
  "mds-button": [
4123
- "mds-spinner",
4124
4269
  "mds-icon",
4270
+ "mds-spinner",
4125
4271
  "mds-text"
4126
4272
  ]
4127
4273
  },
@@ -4288,8 +4434,8 @@
4288
4434
  "mds-button"
4289
4435
  ],
4290
4436
  "mds-button": [
4291
- "mds-spinner",
4292
4437
  "mds-icon",
4438
+ "mds-spinner",
4293
4439
  "mds-text"
4294
4440
  ]
4295
4441
  },
@@ -4324,9 +4470,9 @@
4324
4470
  }
4325
4471
  ],
4326
4472
  "usage": {
4327
- "1. Description": "The `<mds-button>` web component is the primary interactive action control of the Magma Design System. It renders as a button, or as a link when `href` is set, handling form association, accessibility, loading state, and iconography natively.\n\n#### Semantic Behavior\n\n- **Button vs. link**: Providing `href` renders a real anchor inside the component and gives the host `role=\"link\"`. The browser follows the link, so a modifier or middle click opens it in a new tab and the context menu offers the link actions; `target=\"blank\"` opens a new tab on a plain click too. A `click` listener on the host cancels the navigation with `preventDefault()`, which is how a client-side router takes over. A click from the keyboard, a script or an assistive technology lands on the host and is followed the same way, unless cancelled.\n- **Form association**: Inside a `<form>` the component submits (`type=\"submit\"`, default) or resets (`type=\"reset\"`) it like a native button, with no extra wiring; use `type=\"button\"` to opt out. With `name` set, a submit sends `name=value`, so buttons that submit the same form tell the receiver which one was chosen. A custom element cannot be a submitter, so `event.submitter` is a hidden native button that stands in for the component: it carries the same `name` and `value`, but it is not the `mds-button` element.\n- **Active state**: Mirrors a visual pressed state through the `active` attribute, safe to drive from CSS attribute selectors.\n- **Disabled state**: Blocks pointer and keyboard activation and removes the host from the tab sequence. A disabled `<fieldset>` around the button disables it the same way, as it does a native button, without setting `disabled`.\n- **Await state**: Renders an inline spinner, blocks pointer and keyboard activation, and sets `aria-busy=\"true\"` for assistive tech. The button keeps the focus it had, and a click from a script or an assistive technology neither submits nor resets its form again. Remove the attribute when done - do not set `await=\"false\"`.\n- **Keyboard**: Enter activates the button as a click does, and so does Space, on release, as on a native button; a button with `href` is a link, which Enter follows and Space does not.\n- **Accessibility**: Sets `role=\"button\"` on the host, `role=\"link\"` when `href` is set, whatever the format of the icon; the `label` prop (or slotted text) is rendered as the button text, which names it. Without a label, an `aria-label` or a `title`, the component sets `title` from the last segment of the icon slug (`mi/baseline/delete` -> \"delete\"), which names the icon, not the action; an icon given as inline SVG or base64 has no slug, and leaves the button with no name at all: icon-only buttons need an explicit `aria-label` (or `title`), or an `mds-tooltip` with `relation=\"label\"`. A host with `aria-labelledby` gets no name from the slug, and loses the one it had when the attribute comes later, as it does from the tooltip.\n- **Sizing**: The `size` prop drives padding, font size, and minimum hit area. Do not override dimensions with inline `width` / `height`.\n- **Linking constraint**: `target` is effective only when `href` is set.\n\n#### Component-specific variants and tones\n\nThe shared `variant` / `tone` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md). `<mds-button>` adds:\n\n- **`variant=\"google\"` / `variant=\"apple\"`**: brand-correct chrome for SSO entry points. Do not reuse them for non-SSO buttons.\n- **`tone=\"box\"`**: the `strong` fill with an embossed, raised shadow (`--shadow-box-solid-strong`) and a brighter hover: more marked than `strong`, not less.\n\n#### Other behavioral props\n\n- **`icon`** is an SVG filename slug from the Magma icon library; **`iconPosition`** places the glyph relative to the label (use `right` for forward-motion CTAs).\n- **`truncate`**: `word` (default) keeps the label on one line and cuts it with an ellipsis, `all` clamps it with `line-clamp` (one line in the button), `none` lets it wrap onto more lines.\n- **`animation`**: `yugop` progressively reveals characters; otherwise text renders immediately.\n- **The first letter** of the label is uppercased. For a name or an identifier that must stay as written (`rdsysadmin`), set `--mds-button-label-transform: none` on the button or on any ancestor: the property inherits, so it also reaches the buttons that other components, `mds-button-dropdown` among them, render in their shadow root.\n",
4328
- "2. Examples": "Correct and idiomatic ways to use the `<mds-button>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Text Button via `label` Prop\n\nThe canonical form. Use the `label` prop for the button's text; it is rendered inside the button and is its accessible name, so screen readers work without extra wiring.\n\n```html\n<mds-button label=\"Conferma azione\" variant=\"primary\" tone=\"strong\"></mds-button>\n```\n\n#### Variant and Tone for Emphasis\n\nPair the same `variant` with a different `tone` to express importance. Do not invent custom colors to dim or saturate.\n\n```html\n<!-- High emphasis: primary call to action -->\n<mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n\n<!-- Medium emphasis: supporting action -->\n<mds-button label=\"Modifica\" variant=\"primary\" tone=\"outline\"></mds-button>\n\n<!-- Low emphasis: in-text or destructive secondary action -->\n<mds-button label=\"Annulla\" variant=\"error\" tone=\"text\"></mds-button>\n```\n\n#### Sizing\n\nUse the `size` prop. Do not override dimensions with inline `width` / `height`.\n\n```html\n<mds-button label=\"Small\" size=\"sm\" variant=\"primary\"></mds-button>\n<mds-button label=\"Medium\" size=\"md\" variant=\"primary\"></mds-button>\n<mds-button label=\"Large\" size=\"lg\" variant=\"primary\"></mds-button>\n<mds-button label=\"Extra large\" size=\"xl\" variant=\"primary\"></mds-button>\n```\n\n#### Button with Icon\n\nReference icons by their filename slug (no `.svg` extension). `icon-position` defaults to `left`; set it to `right` for forward-motion CTAs.\n\n```html\n<!-- Left icon (default) -->\n<mds-button label=\"Aggiungi\" icon=\"mi/baseline/add\" variant=\"primary\" tone=\"weak\"></mds-button>\n\n<!-- Right icon -->\n<mds-button\n label=\"Avanti\"\n icon=\"mi/baseline/arrow-forward\"\n icon-position=\"right\"\n variant=\"primary\"\n></mds-button>\n```\n\n#### Icon-Only Button\n\nOmit `label` and provide `aria-label` (or `title`) explicitly. Without one, the component names the button after the last segment of the icon slug (\"delete\"), which names the icon, not the action.\n\n```html\n<mds-button\n icon=\"mi/baseline/delete\"\n aria-label=\"Elimina elemento\"\n variant=\"error\"\n tone=\"text\"\n></mds-button>\n```\n\nWhen an `mds-tooltip` shows the name of the button, let the tooltip be the name with `relation=\"label\"` instead: the button then needs no `aria-label`, and gets no `title` from the icon slug.\n\n```html\n<mds-button id=\"elimina-btn\" icon=\"mi/baseline/delete\" variant=\"error\" tone=\"text\"></mds-button>\n<mds-tooltip target=\"#elimina-btn\" relation=\"label\">Elimina elemento</mds-tooltip>\n```\n\n#### Hyperlink via `href`\n\nSetting `href` renders a real link: the browser follows it, in a new tab on a modifier or middle click, and the context menu offers the link actions. Use `target=\"blank\"` to open in a new tab on a plain click too; default is `self`.\n\n```html\n<mds-button\n label=\"Visita il sito\"\n href=\"https://example.com\"\n target=\"blank\"\n variant=\"primary\"\n tone=\"outline\"\n></mds-button>\n```\n\n#### Client-Side Routing via `href`\n\nIn a single-page app keep `href` for the link it gives (new tab, context menu, crawlers) and register the router once with `NavigationService`, from `@maggioli-design-system/magma/services`: every component link is then routed on the client on a plain click, with no listener per button. A modifier or middle click, `target=\"blank\"` and a link to another origin stay with the browser; return `false` from the handler for a link the browser is to load.\n\n```html\n<mds-button label=\"Pratiche\" href=\"/pratiche\" variant=\"primary\" tone=\"text\"></mds-button>\n\n<script type=\"module\">\n import { NavigationService } from '@maggioli-design-system/magma/services';\n\n NavigationService.setHandler((href) => router.navigate(href));\n</script>\n```\n\nWithout a registered router, cancel the click on the button and route by hand: the component honours `preventDefault()`. Leave a modifier click alone, so that the browser opens the link in a new tab.\n\n```html\n<script>\n document.querySelector('mds-button[href]').addEventListener('click', (event) => {\n if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;\n event.preventDefault();\n router.navigate(event.currentTarget.href);\n });\n</script>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while a request is in flight. The component renders an inline spinner, blocks pointer activation, and sets `aria-busy=\"true\"`. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-button label=\"Salvataggio in corso...\" await variant=\"primary\"></mds-button>\n```\n\n#### Form Participation\n\n`<mds-button>` is form-associated. Inside a `<form>` it natively triggers submit (`type=\"submit\"`, default) or reset (`type=\"reset\"`). Use `type=\"button\"` for any action that must not submit the form.\n\n```html\n<form action=\"/save\" method=\"post\">\n <mds-input-field label=\"Titolo\">\n <mds-input name=\"title\"></mds-input>\n </mds-input-field>\n\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Reimposta\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button type=\"button\" label=\"Anteprima\" variant=\"primary\" tone=\"text\"></mds-button>\n</form>\n```\n\n#### Several Actions That Submit One Form\n\nGive the buttons the same `name` and a different `value`, as with native submit buttons: the receiver reads which action was chosen from `name`.\n\n```html\n<form action=\"/mail\" method=\"post\">\n <mds-input-field label=\"Oggetto\">\n <mds-input name=\"subject\"></mds-input>\n </mds-input-field>\n\n <!-- the receiver gets action=send or action=draft -->\n <mds-button name=\"action\" value=\"send\" label=\"Invia\" variant=\"primary\"></mds-button>\n <mds-button name=\"action\" value=\"draft\" label=\"Salva come bozza\" tone=\"outline\"></mds-button>\n</form>\n```\n\nWhen your code handles the submit, build the form data with `event.submitter`, as for a native button: it carries the `name` / `value` of the button that was clicked.\n\n```js\nform.addEventListener('submit', (event) => {\n event.preventDefault();\n const data = new FormData(form, event.submitter);\n data.get('action'); // 'send' or 'draft'\n});\n```\n\nTo show one action and keep the others in a menu, use [`mds-button-dropdown`](../mds-button-dropdown/AGENTS.md) with `type=\"submit\"`: its primary action and its menu items send `name` / `value` the same way.\n\n#### Notification Badge via Named Slot\n\nThe `notification` slot accepts an `<mds-notification>`. This is the documented exception to the default-slot-is-text rule.\n\n```html\n<mds-button label=\"Notifiche\" icon=\"mi/baseline/notifications\" variant=\"primary\" tone=\"weak\">\n <mds-notification slot=\"notification\" value=\"12\"></mds-notification>\n</mds-button>\n```\n\n#### SSO Identity Variants\n\n`variant=\"google\"` and `variant=\"apple\"` apply the brand-correct chrome for SSO entry points. Do not reuse them for non-SSO buttons.\n\n```html\n<mds-button label=\"Accedi con Google\" variant=\"google\"></mds-button>\n<mds-button label=\"Accedi con Apple\" variant=\"apple\"></mds-button>\n```\n\n#### Styling Customization\n\nStyle the button only through its documented `--mds-button-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode, named themes and high contrast keep working.\n\n```css\n.featured-action mds-button {\n --mds-button-background: rgb(var(--magma-accent-emphasis));\n --mds-button-color: rgb(var(--magma-accent-on-emphasis));\n --mds-button-radius: var(--magma-radius-lg);\n --mds-button-gap: calc(var(--spacing) * 300);\n}\n\n/* labels that are names or identifiers, shown as written: it inherits, so it reaches the\n buttons inside other components too */\n.tenant-switcher {\n --mds-button-label-transform: none;\n}\n```\n",
4329
- "3. Mistakes": "Common incorrect uses of `<mds-button>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Put HTML in the Default Slot\n\nThe default slot accepts plain text only; nested elements are stripped or break layout. Use the `label` prop for text and the dedicated props/slots for everything else.\n\n```html\n<!-- INCORRECT -->\n<mds-button>\n <span class=\"bold\">Scarica</span>\n <small>(PDF)</small>\n</mds-button>\n\n<!-- CORRECT -->\n<mds-button label=\"Scarica (PDF)\" icon=\"mi/baseline/download\" variant=\"primary\"></mds-button>\n```\n\n#### Do Not Nest `<mds-button>` Inside an Anchor\n\nWrapping the button in `<a>` creates nested interactive controls, breaks keyboard semantics, and fails accessibility audits. Use the `href` prop on the component instead - it renders the link itself.\n\n```html\n<!-- INCORRECT -->\n<a href=\"/login\">\n <mds-button label=\"Accedi\"></mds-button>\n</a>\n\n<!-- CORRECT -->\n<mds-button label=\"Accedi\" href=\"/login\"></mds-button>\n```\n\n#### Do Not Use `mds-button` for a Link Inside a Sentence\n\n`mds-button` is a block-level control with its own typography and padding: inside a sentence it breaks the line and the font. A word or a phrase that links belongs to `<mds-link>`, which takes the font of the text around it.\n\n```html\n<!-- INCORRECT -->\n<mds-text typography=\"paragraph\">\n Leggi l'<mds-button href=\"/privacy\" tone=\"text\" label=\"informativa\"></mds-button> prima di continuare.\n</mds-text>\n\n<!-- CORRECT -->\n<mds-text typography=\"paragraph\">\n Leggi l'<mds-link href=\"/privacy\">informativa</mds-link> prima di continuare.\n</mds-text>\n```\n\n#### Do Not Follow the `href` Yourself in a Click Listener\n\nWith `href` set the component already renders a link the browser follows. Assigning `window.location` in a click listener loads the page a second time and takes a modifier click, which the browser would open in a new tab, into the current one. Either let the browser follow the link, or cancel the click and route on the client.\n\n```js\n// INCORRECT\nbutton.addEventListener('click', () => {\n window.location.href = button.href;\n});\n\n// CORRECT: a client-side router cancels the click and routes\nbutton.addEventListener('click', (event) => {\n if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;\n event.preventDefault();\n router.navigate(button.href);\n});\n```\n\n#### Icon-Only Buttons Without an Accessible Name\n\nWhen `label` is empty, the component derives a `title` from the last segment of the icon slug (\"delete\"), which names the icon, not the action. Always supply an explicit `aria-label` (or `title`) for icon-only buttons, or an `mds-tooltip` with `relation=\"label\"`.\n\n```html\n<!-- INCORRECT -->\n<mds-button icon=\"mi/baseline/delete\" variant=\"error\" tone=\"text\"></mds-button>\n\n<!-- CORRECT -->\n<mds-button\n icon=\"mi/baseline/delete\"\n aria-label=\"Elimina elemento\"\n variant=\"error\"\n tone=\"text\"\n></mds-button>\n```\n\n#### Do Not Build the Form Data Without the Submitter\n\n`new FormData(form)` leaves out the `name` / `value` of the button that submitted the form, as it does for a native submit button. Pass `event.submitter` to read which action was chosen; do not track the clicked button in a variable or a hidden input.\n\n```js\n// INCORRECT: action is missing\nform.addEventListener('submit', (event) => {\n event.preventDefault();\n const data = new FormData(form);\n});\n\n// CORRECT\nform.addEventListener('submit', (event) => {\n event.preventDefault();\n const data = new FormData(form, event.submitter);\n});\n```\n\n#### Do Not Slot `<mds-icon>` to Add an Icon\n\nThe component's `icon` prop renders the SVG through the shared icon-set service and positions it correctly via `icon-position`. Slotting `<mds-icon>` puts it in the text-only default slot, where it is stripped or misaligned.\n\n```html\n<!-- INCORRECT -->\n<mds-button>\n <mds-icon name=\"mi/baseline/add\"></mds-icon>\n Aggiungi\n</mds-button>\n\n<!-- CORRECT -->\n<mds-button label=\"Aggiungi\" icon=\"mi/baseline/add\" variant=\"primary\" tone=\"weak\"></mds-button>\n```\n\n#### Do Not Use Legacy `ghost` or `quiet` Tone Values\n\n`tone=\"ghost\"` and `tone=\"quiet\"` were renamed in Magma 2.0 to `outline` and `text`. The old values are no longer accepted by the typed `ToneBoxVariantType` and silently fall back to the default tone.\n\n```html\n<!-- INCORRECT (Magma 1.x naming) -->\n<mds-button label=\"Modifica\" tone=\"ghost\" variant=\"primary\"></mds-button>\n<mds-button label=\"Annulla\" tone=\"quiet\" variant=\"error\"></mds-button>\n\n<!-- CORRECT (Magma 2.x) -->\n<mds-button label=\"Modifica\" tone=\"outline\" variant=\"primary\"></mds-button>\n<mds-button label=\"Annulla\" tone=\"text\" variant=\"error\"></mds-button>\n```\n\n#### Customize via Documented Vars and Parts, Not Internal Selectors\n\nThe supported customization surface is `--mds-button-*` CSS custom properties plus the two documented shadow parts (`icon`, `label`). Targeting other internals via `::part()`, `>>>`, or undocumented class names couples your code to the Shadow DOM implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-button >>> .text {\n font-weight: bold;\n}\nmds-button::part(spinner) {\n color: red;\n}\n\n/* CORRECT */\nmds-button {\n --mds-button-color: rgb(var(--magma-accent-on-emphasis));\n --mds-button-radius: var(--magma-radius-lg);\n}\nmds-button::part(icon) {\n fill: rgb(var(--magma-warning-fg));\n}\n```\n"
4473
+ "1. Description": "The `<mds-button>` web component is the primary interactive action control of the Magma Design System. It renders as a button, or as a link when `href` is set, handling form association, accessibility, loading state, and iconography natively.\n\n#### Semantic Behavior\n\n- **Button vs. link**: Providing `href` renders a real anchor inside the component and gives the host `role=\"link\"`. The browser follows the link, so a modifier or middle click opens it in a new tab and the context menu offers the link actions; `target=\"blank\"` opens a new tab on a plain click too. A `click` listener on the host cancels the navigation with `preventDefault()`, which is how a client-side router takes over. A click from the keyboard, a script or an assistive technology lands on the host and is followed the same way, unless cancelled.\n- **Form association**: Inside a `<form>` the component submits (`type=\"submit\"`, default) or resets (`type=\"reset\"`) it like a native button, with no extra wiring; use `type=\"button\"` to opt out. With `name` set, a submit sends `name=value`, so buttons that submit the same form tell the receiver which one was chosen. A custom element cannot be a submitter, so `event.submitter` is a hidden native button that stands in for the component: it carries the same `name` and `value`, but it is not the `mds-button` element.\n- **Active state**: Mirrors a visual pressed state through the `active` attribute, safe to drive from CSS attribute selectors. It is cleared when the pointer is released: it does not mark the view you are in, `current` does.\n- **Current state**: `current` marks the button that leads to the view you are in, the current section of a bar or the current view of a switcher. `current` (or `current=\"page\"`) is that view: the button takes no pointer, Enter does nothing, and a click from a script neither navigates nor submits, so going there again never reloads it; it stays in the Tab order, announced with `aria-current=\"page\"` on a link and `aria-current=\"true\"` otherwise. `current=\"section\"` is a view inside it, a record of its list: the same look, but the button stays a link that brings you back, announced with `aria-current=\"true\"`. An `aria-current` written on the host (`step`, `date`) stays as written. The look: an area that weighs less than the hover of the tone, never its ring, so the hover of the other buttons still weighs more. `weak` takes the selected wash of its family (`--magma-accent-surface-selected`, `-wash-soft` for a status variant), `strong` keeps its fill, `outline` and `text` take the wash of their hover, and a variant whose hover keeps the area (`dark` and `light` weak, `light` strong) keeps it too. The label is one weight heavier (`xl` is black already), which marks the state where the area stays under 3:1; the look holds on hover. Never mark the current button with `disabled`, `aria-disabled` or a style of your own.\n- **Disabled state**: Blocks pointer and keyboard activation and removes the host from the tab sequence. A disabled `<fieldset>` around the button disables it the same way, as it does a native button, without setting `disabled`.\n- **Await state**: Renders an inline spinner, blocks pointer and keyboard activation, and sets `aria-busy=\"true\"` for assistive tech. The button keeps the focus it had, and a click from a script or an assistive technology neither submits nor resets its form again. Remove the attribute when done - do not set `await=\"false\"`.\n- **Keyboard**: Enter activates the button as a click does, and so does Space, on release, as on a native button; a button with `href` is a link, which Enter follows and Space does not.\n- **Accessibility**: Sets `role=\"button\"` on the host, `role=\"link\"` when `href` is set, whatever the format of the icon; the `label` prop (or slotted text) is rendered as the button text, which names it. Without a label, an `aria-label` or a `title`, the component sets `title` from the last segment of the icon slug (`mi/baseline/delete` -> \"delete\"), which names the icon, not the action; an icon given as inline SVG or base64 has no slug, and leaves the button with no name at all: icon-only buttons need an explicit `aria-label` (or `title`), or an `mds-tooltip` with `relation=\"label\"`. A host with `aria-labelledby` gets no name from the slug, and loses the one it had when the attribute comes later, as it does from the tooltip.\n- **Sizing**: The `size` prop drives padding, font size, and minimum hit area. Do not override dimensions with inline `width` / `height`.\n- **Linking constraint**: `target` is effective only when `href` is set.\n\n#### Component-specific variants and tones\n\nThe shared `variant` / `tone` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md). `<mds-button>` adds:\n\n- **`variant=\"google\"` / `variant=\"apple\"`**: brand-correct chrome for SSO entry points. Do not reuse them for non-SSO buttons.\n- **`tone=\"box\"`**: the `strong` fill with an embossed, raised shadow (`--shadow-box-solid-strong`) and a brighter hover: more marked than `strong`, not less.\n\n#### Other behavioral props\n\n- **`icon`** is an SVG filename slug from the Magma icon library; **`iconPosition`** places the glyph relative to the label (use `right` for forward-motion CTAs).\n- **`iconCurrent`** and **`iconHover`** take the place of `icon` in their state: `iconCurrent` on the current button, `iconHover` under the pointer, which falls back on `iconCurrent`. One attribute gives the common pair, an outline icon at rest and the filled one on the current button, which the pointer previews on the others. Set `iconHover` to the `icon` to keep the icon still under the pointer, when `iconCurrent` says something the click does not do (a check). A pointer that cannot hover, a finger, never shows `iconHover`; the current button shows `iconCurrent` under the pointer too. Both need `icon`, which gives the icon its room, and the name taken from the slug stays the one of `icon`. Write every slug out whole, as for `icon`: the icons a product serves are the ones read in its sources.\n- **`truncate`**: `word` (default) keeps the label on one line and cuts it with an ellipsis, `all` clamps it with `line-clamp` (one line in the button), `none` lets it wrap onto more lines.\n- **`animation`**: `yugop` progressively reveals characters; otherwise text renders immediately.\n- **The first letter** of the label is uppercased. For a name or an identifier that must stay as written (`rdsysadmin`), set `--mds-button-label-transform: none` on the button or on any ancestor: the property inherits, so it also reaches the buttons that other components, `mds-button-dropdown` among them, render in their shadow root.\n",
4474
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-button>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Text Button via `label` Prop\n\nThe canonical form. Use the `label` prop for the button's text; it is rendered inside the button and is its accessible name, so screen readers work without extra wiring.\n\n```html\n<mds-button label=\"Conferma azione\" variant=\"primary\" tone=\"strong\"></mds-button>\n```\n\n#### Variant and Tone for Emphasis\n\nPair the same `variant` with a different `tone` to express importance. Do not invent custom colors to dim or saturate.\n\n```html\n<!-- High emphasis: primary call to action -->\n<mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n\n<!-- Medium emphasis: supporting action -->\n<mds-button label=\"Modifica\" variant=\"primary\" tone=\"outline\"></mds-button>\n\n<!-- Low emphasis: in-text or destructive secondary action -->\n<mds-button label=\"Annulla\" variant=\"error\" tone=\"text\"></mds-button>\n```\n\n#### Sizing\n\nUse the `size` prop. Do not override dimensions with inline `width` / `height`.\n\n```html\n<mds-button label=\"Small\" size=\"sm\" variant=\"primary\"></mds-button>\n<mds-button label=\"Medium\" size=\"md\" variant=\"primary\"></mds-button>\n<mds-button label=\"Large\" size=\"lg\" variant=\"primary\"></mds-button>\n<mds-button label=\"Extra large\" size=\"xl\" variant=\"primary\"></mds-button>\n```\n\n#### Button with Icon\n\nReference icons by their filename slug (no `.svg` extension). `icon-position` defaults to `left`; set it to `right` for forward-motion CTAs.\n\n```html\n<!-- Left icon (default) -->\n<mds-button label=\"Aggiungi\" icon=\"mi/baseline/add\" variant=\"primary\" tone=\"weak\"></mds-button>\n\n<!-- Right icon -->\n<mds-button\n label=\"Avanti\"\n icon=\"mi/baseline/arrow-forward\"\n icon-position=\"right\"\n variant=\"primary\"\n></mds-button>\n```\n\n#### Icon-Only Button\n\nOmit `label` and provide `aria-label` (or `title`) explicitly. Without one, the component names the button after the last segment of the icon slug (\"delete\"), which names the icon, not the action.\n\n```html\n<mds-button\n icon=\"mi/baseline/delete\"\n aria-label=\"Elimina elemento\"\n variant=\"error\"\n tone=\"text\"\n></mds-button>\n```\n\nWhen an `mds-tooltip` shows the name of the button, let the tooltip be the name with `relation=\"label\"` instead: the button then needs no `aria-label`, and gets no `title` from the icon slug.\n\n```html\n<mds-button id=\"elimina-btn\" icon=\"mi/baseline/delete\" variant=\"error\" tone=\"text\"></mds-button>\n<mds-tooltip target=\"#elimina-btn\" relation=\"label\">Elimina elemento</mds-tooltip>\n```\n\n#### Hyperlink via `href`\n\nSetting `href` renders a real link: the browser follows it, in a new tab on a modifier or middle click, and the context menu offers the link actions. Use `target=\"blank\"` to open in a new tab on a plain click too; default is `self`.\n\n```html\n<mds-button\n label=\"Visita il sito\"\n href=\"https://example.com\"\n target=\"blank\"\n variant=\"primary\"\n tone=\"outline\"\n></mds-button>\n```\n\n#### Client-Side Routing via `href`\n\nIn a single-page app keep `href` for the link it gives (new tab, context menu, crawlers) and register the router once with `NavigationService`, from `@maggioli-design-system/magma/services`: every component link is then routed on the client on a plain click, with no listener per button. A modifier or middle click, `target=\"blank\"` and a link to another origin stay with the browser; return `false` from the handler for a link the browser is to load.\n\n```html\n<mds-button label=\"Pratiche\" href=\"/pratiche\" variant=\"primary\" tone=\"text\"></mds-button>\n\n<script type=\"module\">\n import { NavigationService } from '@maggioli-design-system/magma/services';\n\n NavigationService.setHandler((href) => router.navigate(href));\n</script>\n```\n\nWithout a registered router, cancel the click on the button and route by hand: the component honours `preventDefault()`. Leave a modifier click alone, so that the browser opens the link in a new tab.\n\n```html\n<script>\n document.querySelector('mds-button[href]').addEventListener('click', (event) => {\n if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;\n event.preventDefault();\n router.navigate(event.currentTarget.href);\n });\n</script>\n```\n\n#### The Current Section via `current`\n\nMark the button that leads to the view you are in with `current`: the section of the bar of the page on screen, the view of a switcher. It does nothing when clicked, so it never reloads the page, and it is announced as the current page. On a page inside a section, a record of its list, write `current=\"section\"`: the same look, and the button stays a link back to the list.\n\n```html\n<!-- the list of the records: Pratiche is the page on screen -->\n<mds-header-bar>\n <mds-text typography=\"h6\" tag=\"p\">Servizi demografici</mds-text>\n <mds-button slot=\"nav\" href=\"/pratiche\" variant=\"dark\" tone=\"text\" current>Pratiche</mds-button>\n <mds-button slot=\"nav\" href=\"/contatti\" variant=\"dark\" tone=\"text\">Contatti</mds-button>\n</mds-header-bar>\n\n<!-- one record of the list: Pratiche brings you back to it -->\n<mds-button slot=\"nav\" href=\"/pratiche\" variant=\"dark\" tone=\"text\" current=\"section\">Pratiche</mds-button>\n\n<!-- the view of a switcher, with no page of its own: aria-current=\"true\" -->\n<mds-button label=\"Lista\" tone=\"weak\" type=\"button\" current></mds-button>\n<mds-button label=\"Mappa\" tone=\"weak\" type=\"button\"></mds-button>\n```\n\n#### The Icon of Each State via `icon-current` and `icon-hover`\n\n`icon-current` takes the place of `icon` on the current button, and under the pointer too, which previews it on the other buttons: one attribute gives an outline icon at rest and the filled one on the view you are in. `icon-hover` sets the icon under the pointer on its own; set it to the `icon` to keep the icon still, when the icon of the current button says something the click does not do. Write the slugs out whole.\n\n```html\n<!-- outline at rest, filled on the current section and under the pointer -->\n<mds-button\n slot=\"nav\"\n href=\"/pratiche\"\n variant=\"dark\"\n tone=\"text\"\n icon=\"mi/outline/folder\"\n icon-current=\"mi/baseline/folder\"\n current\n>Pratiche</mds-button>\n<mds-button\n slot=\"nav\"\n href=\"/contatti\"\n variant=\"dark\"\n tone=\"text\"\n icon=\"mi/outline/contacts\"\n icon-current=\"mi/baseline/contacts\"\n>Contatti</mds-button>\n\n<!-- a check on the current view, and none under the pointer: it would say the view is chosen -->\n<mds-button\n label=\"Elenco\"\n tone=\"weak\"\n type=\"button\"\n icon=\"mi/baseline/view-list\"\n icon-current=\"mi/baseline/check\"\n icon-hover=\"mi/baseline/view-list\"\n current\n></mds-button>\n<mds-button\n label=\"Griglia\"\n tone=\"weak\"\n type=\"button\"\n icon=\"mi/baseline/grid-view\"\n icon-current=\"mi/baseline/check\"\n icon-hover=\"mi/baseline/grid-view\"\n></mds-button>\n\n<!-- another icon under the pointer only -->\n<mds-button\n icon=\"mi/baseline/close\"\n icon-hover=\"mi/outline/close\"\n aria-label=\"Chiudi\"\n variant=\"dark\"\n tone=\"text\"\n></mds-button>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while a request is in flight. The component renders an inline spinner, blocks pointer activation, and sets `aria-busy=\"true\"`. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-button label=\"Salvataggio in corso...\" await variant=\"primary\"></mds-button>\n```\n\n#### Form Participation\n\n`<mds-button>` is form-associated. Inside a `<form>` it natively triggers submit (`type=\"submit\"`, default) or reset (`type=\"reset\"`). Use `type=\"button\"` for any action that must not submit the form.\n\n```html\n<form action=\"/save\" method=\"post\">\n <mds-input-field label=\"Titolo\">\n <mds-input name=\"title\"></mds-input>\n </mds-input-field>\n\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Reimposta\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button type=\"button\" label=\"Anteprima\" variant=\"primary\" tone=\"text\"></mds-button>\n</form>\n```\n\n#### Several Actions That Submit One Form\n\nGive the buttons the same `name` and a different `value`, as with native submit buttons: the receiver reads which action was chosen from `name`.\n\n```html\n<form action=\"/mail\" method=\"post\">\n <mds-input-field label=\"Oggetto\">\n <mds-input name=\"subject\"></mds-input>\n </mds-input-field>\n\n <!-- the receiver gets action=send or action=draft -->\n <mds-button name=\"action\" value=\"send\" label=\"Invia\" variant=\"primary\"></mds-button>\n <mds-button name=\"action\" value=\"draft\" label=\"Salva come bozza\" tone=\"outline\"></mds-button>\n</form>\n```\n\nWhen your code handles the submit, build the form data with `event.submitter`, as for a native button: it carries the `name` / `value` of the button that was clicked.\n\n```js\nform.addEventListener('submit', (event) => {\n event.preventDefault();\n const data = new FormData(form, event.submitter);\n data.get('action'); // 'send' or 'draft'\n});\n```\n\nTo show one action and keep the others in a menu, use [`mds-button-dropdown`](../mds-button-dropdown/AGENTS.md) with `type=\"submit\"`: its primary action and its menu items send `name` / `value` the same way.\n\n#### Notification Badge via Named Slot\n\nThe `notification` slot accepts an `<mds-notification>`. This is the documented exception to the default-slot-is-text rule.\n\n```html\n<mds-button label=\"Notifiche\" icon=\"mi/baseline/notifications\" variant=\"primary\" tone=\"weak\">\n <mds-notification slot=\"notification\" value=\"12\"></mds-notification>\n</mds-button>\n```\n\n#### SSO Identity Variants\n\n`variant=\"google\"` and `variant=\"apple\"` apply the brand-correct chrome for SSO entry points. Do not reuse them for non-SSO buttons.\n\n```html\n<mds-button label=\"Accedi con Google\" variant=\"google\"></mds-button>\n<mds-button label=\"Accedi con Apple\" variant=\"apple\"></mds-button>\n```\n\n#### Styling Customization\n\nStyle the button only through its documented `--mds-button-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode, named themes and high contrast keep working.\n\n```css\n.featured-action mds-button {\n --mds-button-background: rgb(var(--magma-accent-emphasis));\n --mds-button-color: rgb(var(--magma-accent-on-emphasis));\n --mds-button-radius: var(--magma-radius-lg);\n --mds-button-gap: calc(var(--spacing) * 300);\n}\n\n/* labels that are names or identifiers, shown as written: it inherits, so it reaches the\n buttons inside other components too */\n.tenant-switcher {\n --mds-button-label-transform: none;\n}\n```\n",
4475
+ "3. Mistakes": "Common incorrect uses of `<mds-button>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Put HTML in the Default Slot\n\nThe default slot accepts plain text only; nested elements are stripped or break layout. Use the `label` prop for text and the dedicated props/slots for everything else.\n\n```html\n<!-- INCORRECT -->\n<mds-button>\n <span class=\"bold\">Scarica</span>\n <small>(PDF)</small>\n</mds-button>\n\n<!-- CORRECT -->\n<mds-button label=\"Scarica (PDF)\" icon=\"mi/baseline/download\" variant=\"primary\"></mds-button>\n```\n\n#### Do Not Nest `<mds-button>` Inside an Anchor\n\nWrapping the button in `<a>` creates nested interactive controls, breaks keyboard semantics, and fails accessibility audits. Use the `href` prop on the component instead - it renders the link itself.\n\n```html\n<!-- INCORRECT -->\n<a href=\"/login\">\n <mds-button label=\"Accedi\"></mds-button>\n</a>\n\n<!-- CORRECT -->\n<mds-button label=\"Accedi\" href=\"/login\"></mds-button>\n```\n\n#### Do Not Use `mds-button` for a Link Inside a Sentence\n\n`mds-button` is a block-level control with its own typography and padding: inside a sentence it breaks the line and the font. A word or a phrase that links belongs to `<mds-link>`, which takes the font of the text around it.\n\n```html\n<!-- INCORRECT -->\n<mds-text typography=\"paragraph\">\n Leggi l'<mds-button href=\"/privacy\" tone=\"text\" label=\"informativa\"></mds-button> prima di continuare.\n</mds-text>\n\n<!-- CORRECT -->\n<mds-text typography=\"paragraph\">\n Leggi l'<mds-link href=\"/privacy\">informativa</mds-link> prima di continuare.\n</mds-text>\n```\n\n#### Do Not Follow the `href` Yourself in a Click Listener\n\nWith `href` set the component already renders a link the browser follows. Assigning `window.location` in a click listener loads the page a second time and takes a modifier click, which the browser would open in a new tab, into the current one. Either let the browser follow the link, or cancel the click and route on the client.\n\n```js\n// INCORRECT\nbutton.addEventListener('click', () => {\n window.location.href = button.href;\n});\n\n// CORRECT: a client-side router cancels the click and routes\nbutton.addEventListener('click', (event) => {\n if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;\n event.preventDefault();\n router.navigate(button.href);\n});\n```\n\n#### Icon-Only Buttons Without an Accessible Name\n\nWhen `label` is empty, the component derives a `title` from the last segment of the icon slug (\"delete\"), which names the icon, not the action. Always supply an explicit `aria-label` (or `title`) for icon-only buttons, or an `mds-tooltip` with `relation=\"label\"`.\n\n```html\n<!-- INCORRECT -->\n<mds-button icon=\"mi/baseline/delete\" variant=\"error\" tone=\"text\"></mds-button>\n\n<!-- CORRECT -->\n<mds-button\n icon=\"mi/baseline/delete\"\n aria-label=\"Elimina elemento\"\n variant=\"error\"\n tone=\"text\"\n></mds-button>\n```\n\n#### Do Not Build the Form Data Without the Submitter\n\n`new FormData(form)` leaves out the `name` / `value` of the button that submitted the form, as it does for a native submit button. Pass `event.submitter` to read which action was chosen; do not track the clicked button in a variable or a hidden input.\n\n```js\n// INCORRECT: action is missing\nform.addEventListener('submit', (event) => {\n event.preventDefault();\n const data = new FormData(form);\n});\n\n// CORRECT\nform.addEventListener('submit', (event) => {\n event.preventDefault();\n const data = new FormData(form, event.submitter);\n});\n```\n\n#### Do Not Slot `<mds-icon>` to Add an Icon\n\nThe component's `icon` prop renders the SVG through the shared icon-set service and positions it correctly via `icon-position`. Slotting `<mds-icon>` puts it in the text-only default slot, where it is stripped or misaligned.\n\n```html\n<!-- INCORRECT -->\n<mds-button>\n <mds-icon name=\"mi/baseline/add\"></mds-icon>\n Aggiungi\n</mds-button>\n\n<!-- CORRECT -->\n<mds-button label=\"Aggiungi\" icon=\"mi/baseline/add\" variant=\"primary\" tone=\"weak\"></mds-button>\n```\n\n#### Do Not Mark the Current Button by Hand, Nor Disable It\n\nThe button of the view you are in takes `current`. A tone switched by hand with `aria-current` gives every product its own look (and `tone=\"weak\"` alone stays under the 3:1 of a state), `active` is the pressed look and is cleared when the pointer is released, and `disabled` takes the button out of the Tab order and announces it as unavailable, so the keyboard never learns where it is.\n\n```html\n<!-- INCORRECT -->\n<mds-button href=\"/pratiche\" variant=\"dark\" tone=\"weak\" aria-current=\"page\">Pratiche</mds-button>\n<mds-button href=\"/pratiche\" variant=\"dark\" tone=\"text\" active>Pratiche</mds-button>\n<mds-button href=\"/pratiche\" variant=\"dark\" tone=\"text\" disabled>Pratiche</mds-button>\n\n<!-- CORRECT -->\n<mds-button href=\"/pratiche\" variant=\"dark\" tone=\"text\" current>Pratiche</mds-button>\n```\n\n#### Do Not Swap the Icon by Hand\n\nA listener that changes `icon` under the pointer fetches the new icon the first time it comes, so the button shows no icon until it arrives, and leaves it on what a finger tapped. A slug built at runtime is never served: the icons a product serves are the ones written in its sources. Use `icon-current` and `icon-hover`, with the slugs written out whole.\n\n```js\n// INCORRECT\nbutton.addEventListener('mouseenter', () => (button.icon = 'mi/baseline/folder'));\nbutton.addEventListener('mouseleave', () => (button.icon = 'mi/outline/folder'));\nbutton.icon = `mi/${here ? 'baseline' : 'outline'}/folder`;\n```\n\n```html\n<!-- CORRECT -->\n<mds-button\n href=\"/pratiche\"\n icon=\"mi/outline/folder\"\n icon-current=\"mi/baseline/folder\"\n current\n>Pratiche</mds-button>\n```\n\n#### Do Not Use Legacy `ghost` or `quiet` Tone Values\n\n`tone=\"ghost\"` and `tone=\"quiet\"` were renamed in Magma 2.0 to `outline` and `text`. The old values are no longer accepted by the typed `ToneBoxVariantType` and silently fall back to the default tone.\n\n```html\n<!-- INCORRECT (Magma 1.x naming) -->\n<mds-button label=\"Modifica\" tone=\"ghost\" variant=\"primary\"></mds-button>\n<mds-button label=\"Annulla\" tone=\"quiet\" variant=\"error\"></mds-button>\n\n<!-- CORRECT (Magma 2.x) -->\n<mds-button label=\"Modifica\" tone=\"outline\" variant=\"primary\"></mds-button>\n<mds-button label=\"Annulla\" tone=\"text\" variant=\"error\"></mds-button>\n```\n\n#### Customize via Documented Vars and Parts, Not Internal Selectors\n\nThe supported customization surface is `--mds-button-*` CSS custom properties plus the two documented shadow parts (`icon`, `label`). Targeting other internals via `::part()`, `>>>`, or undocumented class names couples your code to the Shadow DOM implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-button >>> .text {\n font-weight: bold;\n}\nmds-button::part(spinner) {\n color: red;\n}\n\n/* CORRECT */\nmds-button {\n --mds-button-color: rgb(var(--magma-accent-on-emphasis));\n --mds-button-radius: var(--magma-radius-lg);\n}\nmds-button::part(icon) {\n fill: rgb(var(--magma-warning-fg));\n}\n```\n"
4330
4476
  },
4331
4477
  "props": [
4332
4478
  {
@@ -4445,6 +4591,47 @@
4445
4591
  "getter": false,
4446
4592
  "setter": false
4447
4593
  },
4594
+ {
4595
+ "name": "current",
4596
+ "type": "\"page\" | \"section\" | boolean | undefined",
4597
+ "complexType": {
4598
+ "original": "ButtonCurrentType",
4599
+ "resolved": "\"page\" | \"section\" | boolean | undefined",
4600
+ "references": {
4601
+ "ButtonCurrentType": {
4602
+ "location": "import",
4603
+ "path": "@type/button",
4604
+ "id": "src/type/button.ts::ButtonCurrentType",
4605
+ "referenceLocation": "ButtonCurrentType"
4606
+ }
4607
+ }
4608
+ },
4609
+ "mutable": false,
4610
+ "attr": "current",
4611
+ "reflectToAttr": true,
4612
+ "docs": "Marks the button that leads to the view you are in, as the current section of a bar or the\ncurrent view of a switcher, with a look of its own: an area that weighs less than the hover of\nits tone, never its ring, and a heavier label. `current`, or\n`current=\"page\"`, is that view: the button neither navigates nor submits, a click and Enter do\nnothing, but it stays in the Tab order, announced with `aria-current` (`\"page\"` on a link,\n`\"true\"` otherwise). `current=\"section\"` is a view inside it, as a record of its list: the\nsame look, and the button stays a link that brings you back, announced with\n`aria-current=\"true\"`. An `aria-current` written on the host stays as written.",
4613
+ "docsTags": [],
4614
+ "values": [
4615
+ {
4616
+ "value": "page",
4617
+ "type": "string"
4618
+ },
4619
+ {
4620
+ "value": "section",
4621
+ "type": "string"
4622
+ },
4623
+ {
4624
+ "type": "boolean"
4625
+ },
4626
+ {
4627
+ "type": "undefined"
4628
+ }
4629
+ ],
4630
+ "optional": true,
4631
+ "required": false,
4632
+ "getter": false,
4633
+ "setter": false
4634
+ },
4448
4635
  {
4449
4636
  "name": "disabled",
4450
4637
  "type": "boolean | undefined",
@@ -4508,7 +4695,59 @@
4508
4695
  "mutable": true,
4509
4696
  "attr": "icon",
4510
4697
  "reflectToAttr": true,
4511
- "docs": "The icon displayed in the button",
4698
+ "docs": "The icon displayed in the button; `iconCurrent` and `iconHover` take its place in their\nstates",
4699
+ "docsTags": [],
4700
+ "values": [
4701
+ {
4702
+ "type": "string"
4703
+ },
4704
+ {
4705
+ "type": "undefined"
4706
+ }
4707
+ ],
4708
+ "optional": true,
4709
+ "required": false,
4710
+ "getter": false,
4711
+ "setter": false
4712
+ },
4713
+ {
4714
+ "name": "iconCurrent",
4715
+ "type": "string | undefined",
4716
+ "complexType": {
4717
+ "original": "string",
4718
+ "resolved": "string | undefined",
4719
+ "references": {}
4720
+ },
4721
+ "mutable": false,
4722
+ "attr": "icon-current",
4723
+ "reflectToAttr": false,
4724
+ "docs": "The icon of the current button, in place of `icon`: the filled icon, say, of an `icon` drawn\nas an outline. It is the icon under the pointer too, unless `iconHover` says otherwise, so\nthe pointer previews it on the buttons that are not current. It takes the place of `icon`:\nwithout `icon` it shows nothing",
4725
+ "docsTags": [],
4726
+ "values": [
4727
+ {
4728
+ "type": "string"
4729
+ },
4730
+ {
4731
+ "type": "undefined"
4732
+ }
4733
+ ],
4734
+ "optional": true,
4735
+ "required": false,
4736
+ "getter": false,
4737
+ "setter": false
4738
+ },
4739
+ {
4740
+ "name": "iconHover",
4741
+ "type": "string | undefined",
4742
+ "complexType": {
4743
+ "original": "string",
4744
+ "resolved": "string | undefined",
4745
+ "references": {}
4746
+ },
4747
+ "mutable": false,
4748
+ "attr": "icon-hover",
4749
+ "reflectToAttr": false,
4750
+ "docs": "The icon under the pointer, in place of `icon`, and `iconCurrent` when it is not set. Set it\nto the `icon` to keep the icon still under the pointer, when `iconCurrent` says something\nthe click does not do (a check, say). A pointer that cannot hover, as a finger, never shows\nit. It takes the place of `icon`: without `icon` it shows nothing",
4512
4751
  "docsTags": [],
4513
4752
  "values": [
4514
4753
  {
@@ -5130,14 +5369,14 @@
5130
5369
  "mds-url-view"
5131
5370
  ],
5132
5371
  "dependencies": [
5133
- "mds-spinner",
5134
5372
  "mds-icon",
5373
+ "mds-spinner",
5135
5374
  "mds-text"
5136
5375
  ],
5137
5376
  "dependencyGraph": {
5138
5377
  "mds-button": [
5139
- "mds-spinner",
5140
5378
  "mds-icon",
5379
+ "mds-spinner",
5141
5380
  "mds-text"
5142
5381
  ],
5143
5382
  "mds-banner": [
@@ -5263,8 +5502,8 @@
5263
5502
  }
5264
5503
  ],
5265
5504
  "usage": {
5266
- "1. Description": "The `<mds-button-dropdown>` web component is a split-button control of the Magma Design System: it pairs a primary `<mds-button>` action with a secondary chevron button that opens an attached `<mds-dropdown>`, giving users a default action plus a menu of related choices in a single, visually unified control.\n\n#### Semantic Behavior\n\n- **Default slot is the menu**: Whatever you place in the default slot becomes the dropdown panel content; it is not treated as the button label (the visible label comes from the `label` prop).\n- **Chevron trigger**: The second button is icon-only (chevron), named in the page language (the `lang` of `<html>`) (\"More actions\"), and toggles the dropdown; it carries `aria-haspopup` and `aria-expanded` for the menu it opens.\n- **Shared configuration**: `active`, `await`, `disabled`, `size`, `tone` and `variant` are forwarded identically to both internal buttons, so the two halves always stay visually and behaviorally in sync. `href`, `target` and `autoFocus` belong to the primary action alone: the chevron only opens the menu.\n- **Form association**: The host is form-associated. With `type=\"submit\"` the primary action submits the enclosing `<form>` (or the one its `form` attribute names) and sends `name=value`, like a native submit button; with `type=\"reset\"` it resets it. The chevron never submits. Unlike `<mds-button>`, `type` defaults to `'button'`: a dropdown in a form submits it only when asked. The menu items are slotted `<mds-button>`, so they follow their own `type` (default `'submit'`), `name` and `value`, and the receiver tells all the actions apart by `name`.\n- **Disabled / await states**: Because these flags pass through to both buttons, disabling or putting the control in an awaiting state affects the action and the trigger together. A disabled `<fieldset>` around the component disables both halves the same way, without setting `disabled`.\n- **Primary action event**: `mdsButtonDropdownClick` fires when the primary action is clicked or activated from the keyboard, and not while the component is `disabled` or awaiting. The chevron and the menu items do not fire it. A native `click` listener on the component also runs for the menu items, whose clicks bubble to it, so listen for `mdsButtonDropdownClick` to run the primary action in JavaScript.\n- **Dropdown part**: The internal dropdown is exposed as the `dropdown` shadow part for external styling of the menu surface.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` / `tone` / `size` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md); they apply here as in `<mds-button>`, narrowed to `tone` `strong` / `weak` and without the `google` / `apple` variants, and are forwarded to both internal buttons. `variant` defaults to `'primary'`, `tone` defaults to `'strong'`, and `size` defaults to `'md'`.\n\n- **`label`** sets the text of the primary action button only; the chevron trigger is icon-only.\n- **`type`** (default `'button'`), **`name`** and **`value`** apply to the primary action only, as described under Form association. The menu items follow their own `type`: inside a `<form>`, give `type=\"button\"` to the ones that must not submit it.\n- **`href`** makes the primary action a link that navigates instead of submitting, with `target` choosing `'self'` vs `'blank'`; the chevron still opens the menu.\n\n#### Other behavioral props\n\n- **`autoFocus`** focuses the primary action once the component is loaded.\n- **`icon`** is an SVG filename slug from the Magma icon library, applied to the primary action button (the chevron icon on the trigger is fixed and not configurable).\n- **`truncate`** sets how the label of the primary action truncates, as on `mds-button` (default `'word'`).\n",
5267
- "2. Examples": "Correct and idiomatic ways to use the `<mds-button-dropdown>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Split Button with Menu Items\n\nThe canonical form: a `label` prop for the primary action and one or more [`mds-button`](../mds-button/AGENTS.md) elements in the default slot as menu choices. Give the slot items `variant=\"dark\" tone=\"text\"` to keep them visually neutral inside the dropdown panel.\n\n```html\n<mds-button-dropdown label=\"Salva come bozza\" variant=\"success\" tone=\"weak\">\n <mds-button icon=\"mi/baseline/send\" variant=\"dark\" tone=\"text\" label=\"Invia subito\"></mds-button>\n <mds-button icon=\"mi/baseline/delete\" variant=\"dark\" tone=\"text\" label=\"Elimina\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Variant and Tone for Emphasis\n\nUse `variant` to express meaning and `tone` to express weight - the same pair applies to both internal buttons automatically.\n\n```html\n<!-- High emphasis: primary action -->\n<mds-button-dropdown label=\"Pubblica\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Pubblica come bozza\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Pianifica pubblicazione\"></mds-button>\n</mds-button-dropdown>\n\n<!-- Status emphasis: destructive action group -->\n<mds-button-dropdown label=\"Elimina voce\" variant=\"error\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Elimina e archivia\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Annulla eliminazione\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Sizing\n\nUse the `size` prop. Both internal buttons track it automatically.\n\n```html\n<mds-button-dropdown label=\"Azione\" size=\"sm\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"md\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"lg\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"xl\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Primary Action with an Icon\n\nSupply the `icon` prop to add an icon to the primary action button. The chevron trigger icon is fixed and not configurable.\n\n```html\n<mds-button-dropdown\n label=\"Carica documento\"\n icon=\"mi/baseline/upload\"\n variant=\"primary\"\n tone=\"weak\"\n>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Carica da URL\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Carica da Drive\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while a request is in flight. Both the action button and the chevron trigger become unavailable simultaneously. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-button-dropdown label=\"Salvataggio in corso...\" await variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Salva e chiudi\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Salva come copia\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Disabled State\n\nThe `disabled` attribute blocks both halves of the control together.\n\n```html\n<mds-button-dropdown label=\"Invia richiesta\" disabled variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Invia in bozza\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Primary Action Handled in JavaScript\n\nListen for `mdsButtonDropdownClick` to run the primary action: it comes from the primary action only, from a click or the keyboard, and not while the component is `disabled` or awaiting. Handle each menu item with its own `click`.\n\n```html\n<mds-button-dropdown id=\"save\" label=\"Salva\" variant=\"primary\">\n <mds-button id=\"save-copy\" variant=\"dark\" tone=\"text\" label=\"Salva come copia\"></mds-button>\n</mds-button-dropdown>\n\n<script>\n document.getElementById('save').addEventListener('mdsButtonDropdownClick', () => save());\n document.getElementById('save-copy').addEventListener('click', () => saveCopy());\n</script>\n```\n\n#### Several Actions That Submit One Form\n\nSet `type=\"submit\"` on the component and give the primary action and the menu items the same `name` with a different `value`: each action submits the form, and the receiver reads which one was chosen from `name`, as with native submit buttons. Give `type=\"button\"` to the menu items that must not submit.\n\n```html\n<form action=\"/mail\" method=\"post\">\n <mds-input-field label=\"Oggetto\">\n <mds-input name=\"subject\"></mds-input>\n </mds-input-field>\n\n <!-- the receiver gets action=send, action=draft or action=schedule -->\n <mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\" variant=\"primary\">\n <mds-button name=\"action\" value=\"draft\" variant=\"dark\" tone=\"text\" label=\"Salva come bozza\"></mds-button>\n <mds-button name=\"action\" value=\"schedule\" variant=\"dark\" tone=\"text\" label=\"Invio programmato\"></mds-button>\n <mds-button type=\"button\" variant=\"dark\" tone=\"text\" label=\"Anteprima\"></mds-button>\n </mds-button-dropdown>\n</form>\n```\n\nWhen your code handles the submit, build the form data with `event.submitter`, as for [`mds-button`](../mds-button/AGENTS.md): `new FormData(form, event.submitter)`.\n\n#### Hyperlink Split Button via `href`\n\n`href` and `target` on the component make the primary action a link; the chevron keeps opening the menu. Put the other links on the menu items (`target=\"blank\"` opens them in a new tab).\n\n```html\n<mds-button-dropdown\n label=\"Apri documento\"\n href=\"https://example.com/doc\"\n variant=\"primary\"\n tone=\"weak\"\n>\n <mds-button href=\"https://example.com/doc/edit\" target=\"blank\" variant=\"dark\" tone=\"text\" label=\"Modifica\"></mds-button>\n <mds-button href=\"https://example.com/doc/history\" target=\"blank\" variant=\"dark\" tone=\"text\" label=\"Cronologia\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Styling Customization\n\nStyle the component through its documented `--mds-button-dropdown-*` CSS custom properties or the `dropdown` shadow part. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and named themes keep working.\n\nThe `--mds-button-*` properties that inherit reach the two inner buttons too: `--mds-button-label-transform: none` on the component keeps a label such as a tenant name as written, without the uppercase first letter.\n\n```css\n.custom-toolbar mds-button-dropdown {\n --mds-button-dropdown-radius: var(--magma-radius-md);\n}\n\n.tenant-switcher mds-button-dropdown {\n --mds-button-label-transform: none;\n}\n\n/* Style the dropdown panel surface through the documented shadow part */\n.custom-toolbar mds-button-dropdown::part(dropdown) {\n box-shadow: var(--shadow-lg);\n}\n```\n",
5505
+ "1. Description": "The `<mds-button-dropdown>` web component is a split-button control of the Magma Design System: it pairs a primary `<mds-button>` action with a secondary chevron button that opens an attached `<mds-dropdown>`, giving users a default action plus a menu of related choices in a single, visually unified control.\n\n#### Semantic Behavior\n\n- **Default slot is the menu**: Whatever you place in the default slot becomes the dropdown panel content; it is not treated as the button label (the visible label comes from the `label` prop).\n- **Chevron trigger**: The second button is icon-only (chevron), named in the page language (the `lang` of `<html>`) (\"More actions\"), and toggles the dropdown; it carries `aria-haspopup` and `aria-expanded` for the menu it opens.\n- **Shared configuration**: `active`, `await`, `disabled`, `size`, `tone` and `variant` are forwarded identically to both internal buttons, so the two halves always stay visually and behaviorally in sync. `href`, `target` and `autoFocus` belong to the primary action alone: the chevron only opens the menu.\n- **Current state**: `current` marks the primary action as the one that leads to the view you are in, as on `<mds-button>`. Both halves take the look of the current button; only the primary action is announced with `aria-current` and, with `current` (or `current=\"page\"`), neither navigates, nor submits, nor fires `mdsButtonDropdownClick`. With `current=\"section\"`, a view inside it, the primary action stays a link back. The chevron keeps opening the menu either way. A menu item that leads to the view you are in takes `current` itself.\n- **Form association**: The host is form-associated. With `type=\"submit\"` the primary action submits the enclosing `<form>` (or the one its `form` attribute names) and sends `name=value`, like a native submit button; with `type=\"reset\"` it resets it. The chevron never submits. Unlike `<mds-button>`, `type` defaults to `'button'`: a dropdown in a form submits it only when asked. The menu items are slotted `<mds-button>`, so they follow their own `type` (default `'submit'`), `name` and `value`, and the receiver tells all the actions apart by `name`.\n- **Disabled / await states**: Because these flags pass through to both buttons, disabling or putting the control in an awaiting state affects the action and the trigger together. A disabled `<fieldset>` around the component disables both halves the same way, without setting `disabled`.\n- **Primary action event**: `mdsButtonDropdownClick` fires when the primary action is clicked or activated from the keyboard, and not while the component is `disabled` or awaiting. The chevron and the menu items do not fire it. A native `click` listener on the component also runs for the menu items, whose clicks bubble to it, so listen for `mdsButtonDropdownClick` to run the primary action in JavaScript.\n- **Dropdown part**: The internal dropdown is exposed as the `dropdown` shadow part for external styling of the menu surface.\n- **Corners**: The two halves take their outer corners from the host, the radius of `--mds-button-dropdown-radius`, and meet with flat inner corners. A row that joins the component flattens its corners on the host: in an `<mds-button-group>` the side that touches the next member is flat, on the primary action or on the chevron.\n- **Width**: The component keeps its own width, its primary action as wide as an `<mds-button>` with the same label. A row that stretches it, as `actions/stacked` does under `--magma-container-actions` (380px) in `<mds-card-footer>`, `<mds-banner>`, `<mds-status-bar>` or a row of your own (`align-self: stretch`, a `width`, a `flex-basis`), gives the free width to the primary action, its label in the middle, and keeps the chevron at its own size at the end: the two halves still read as one button, with no fill past them.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` / `tone` / `size` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md); they apply here as in `<mds-button>`, narrowed to `tone` `strong` / `weak` and without the `google` / `apple` variants, and are forwarded to both internal buttons. `variant` defaults to `'primary'`, `tone` defaults to `'strong'`, and `size` defaults to `'md'`.\n\n- **`label`** sets the text of the primary action button only; the chevron trigger is icon-only.\n- **`type`** (default `'button'`), **`name`** and **`value`** apply to the primary action only, as described under Form association. The menu items follow their own `type`: inside a `<form>`, give `type=\"button\"` to the ones that must not submit it.\n- **`href`** makes the primary action a link that navigates instead of submitting, with `target` choosing `'self'` vs `'blank'`; the chevron still opens the menu.\n\n#### Other behavioral props\n\n- **`autoFocus`** focuses the primary action once the component is loaded.\n- **`icon`** is an SVG filename slug from the Magma icon library, applied to the primary action button (the chevron icon on the trigger is fixed and not configurable).\n- **`iconCurrent`** and **`iconHover`** take the place of `icon` on the primary action, when it is current and under the pointer, as on `<mds-button>`: `iconHover` falls back on `iconCurrent`, and both need `icon`. The chevron keeps its arrow.\n- **`truncate`** sets how the label of the primary action truncates, as on `mds-button` (default `'word'`).\n",
5506
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-button-dropdown>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Split Button with Menu Items\n\nThe canonical form: a `label` prop for the primary action and one or more [`mds-button`](../mds-button/AGENTS.md) elements in the default slot as menu choices. Give the slot items `variant=\"dark\" tone=\"text\"` to keep them visually neutral inside the dropdown panel.\n\n```html\n<mds-button-dropdown label=\"Salva come bozza\" variant=\"success\" tone=\"weak\">\n <mds-button icon=\"mi/baseline/send\" variant=\"dark\" tone=\"text\" label=\"Invia subito\"></mds-button>\n <mds-button icon=\"mi/baseline/delete\" variant=\"dark\" tone=\"text\" label=\"Elimina\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Variant and Tone for Emphasis\n\nUse `variant` to express meaning and `tone` to express weight - the same pair applies to both internal buttons automatically.\n\n```html\n<!-- High emphasis: primary action -->\n<mds-button-dropdown label=\"Pubblica\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Pubblica come bozza\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Pianifica pubblicazione\"></mds-button>\n</mds-button-dropdown>\n\n<!-- Status emphasis: destructive action group -->\n<mds-button-dropdown label=\"Elimina voce\" variant=\"error\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Elimina e archivia\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Annulla eliminazione\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Sizing\n\nUse the `size` prop. Both internal buttons track it automatically.\n\n```html\n<mds-button-dropdown label=\"Azione\" size=\"sm\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"md\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"lg\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"xl\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Primary Action with an Icon\n\nSupply the `icon` prop to add an icon to the primary action button. The chevron trigger icon is fixed and not configurable.\n\n```html\n<mds-button-dropdown\n label=\"Carica documento\"\n icon=\"mi/baseline/upload\"\n variant=\"primary\"\n tone=\"weak\"\n>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Carica da URL\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Carica da Drive\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while a request is in flight. Both the action button and the chevron trigger become unavailable simultaneously. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-button-dropdown label=\"Salvataggio in corso...\" await variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Salva e chiudi\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Salva come copia\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Disabled State\n\nThe `disabled` attribute blocks both halves of the control together.\n\n```html\n<mds-button-dropdown label=\"Invia richiesta\" disabled variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Invia in bozza\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Primary Action Handled in JavaScript\n\nListen for `mdsButtonDropdownClick` to run the primary action: it comes from the primary action only, from a click or the keyboard, and not while the component is `disabled` or awaiting. Handle each menu item with its own `click`.\n\n```html\n<mds-button-dropdown id=\"save\" label=\"Salva\" variant=\"primary\">\n <mds-button id=\"save-copy\" variant=\"dark\" tone=\"text\" label=\"Salva come copia\"></mds-button>\n</mds-button-dropdown>\n\n<script>\n document.getElementById('save').addEventListener('mdsButtonDropdownClick', () => save());\n document.getElementById('save-copy').addEventListener('click', () => saveCopy());\n</script>\n```\n\n#### Several Actions That Submit One Form\n\nSet `type=\"submit\"` on the component and give the primary action and the menu items the same `name` with a different `value`: each action submits the form, and the receiver reads which one was chosen from `name`, as with native submit buttons. Give `type=\"button\"` to the menu items that must not submit.\n\n```html\n<form action=\"/mail\" method=\"post\">\n <mds-input-field label=\"Oggetto\">\n <mds-input name=\"subject\"></mds-input>\n </mds-input-field>\n\n <!-- the receiver gets action=send, action=draft or action=schedule -->\n <mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\" variant=\"primary\">\n <mds-button name=\"action\" value=\"draft\" variant=\"dark\" tone=\"text\" label=\"Salva come bozza\"></mds-button>\n <mds-button name=\"action\" value=\"schedule\" variant=\"dark\" tone=\"text\" label=\"Invio programmato\"></mds-button>\n <mds-button type=\"button\" variant=\"dark\" tone=\"text\" label=\"Anteprima\"></mds-button>\n </mds-button-dropdown>\n</form>\n```\n\nWhen your code handles the submit, build the form data with `event.submitter`, as for [`mds-button`](../mds-button/AGENTS.md): `new FormData(form, event.submitter)`.\n\n#### Hyperlink Split Button via `href`\n\n`href` and `target` on the component make the primary action a link; the chevron keeps opening the menu. Put the other links on the menu items (`target=\"blank\"` opens them in a new tab).\n\n```html\n<mds-button-dropdown\n label=\"Apri documento\"\n href=\"https://example.com/doc\"\n variant=\"primary\"\n tone=\"weak\"\n>\n <mds-button href=\"https://example.com/doc/edit\" target=\"blank\" variant=\"dark\" tone=\"text\" label=\"Modifica\"></mds-button>\n <mds-button href=\"https://example.com/doc/history\" target=\"blank\" variant=\"dark\" tone=\"text\" label=\"Cronologia\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### In a Row of Actions That Stacks\n\nStretch the component as any other action of the row: under `--magma-container-actions` of its container (`@max-actions:`), `actions/stacked` puts every labelled button at the full width, and the component gives that width to its primary action, the chevron staying at the end. No part or custom property is needed.\n\n```html\n<div class=\"@container\">\n <div class=\"flex justify-end gap-inline @max-actions:flex-col @max-actions:*:self-stretch\">\n <mds-button variant=\"dark\" tone=\"outline\" label=\"Copia JSON\"></mds-button>\n <mds-button-dropdown label=\"Scarica\" icon=\"mi/baseline/download\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Scarica come CSS\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Scarica come JSON\"></mds-button>\n </mds-button-dropdown>\n </div>\n</div>\n```\n\n#### Styling Customization\n\nStyle the component through its documented `--mds-button-dropdown-*` CSS custom properties or the `dropdown` shadow part. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and named themes keep working.\n\nThe `--mds-button-*` properties that inherit reach the two inner buttons too: `--mds-button-label-transform: none` on the component keeps a label such as a tenant name as written, without the uppercase first letter.\n\n```css\n.custom-toolbar mds-button-dropdown {\n --mds-button-dropdown-radius: var(--magma-radius-md);\n}\n\n.tenant-switcher mds-button-dropdown {\n --mds-button-label-transform: none;\n}\n\n/* Style the dropdown panel surface through the documented shadow part */\n.custom-toolbar mds-button-dropdown::part(dropdown) {\n box-shadow: var(--shadow-lg);\n}\n```\n",
5268
5507
  "3. Mistakes": "Common incorrect uses of `<mds-button-dropdown>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Put the Label in the Default Slot\n\nThe default slot feeds the `<mds-dropdown>` panel, not the button label. Text placed in the slot ends up as menu content, not as the button's visible text. Use the `label` prop.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown variant=\"primary\" tone=\"strong\">\n Salva\n</mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown label=\"Salva\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Salva come bozza\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Slot Non-Button Content as Menu Items\n\nThe dropdown panel is designed for [`mds-button`](../mds-button/AGENTS.md) elements. Slotting raw `<button>`, `<a>`, or arbitrary HTML bypasses the Magma theming, focus styles and button API (`icon`, `await`, `disabled`) of the menu entries.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown label=\"Esporta\" variant=\"primary\" tone=\"weak\">\n <button onclick=\"exportPDF()\">PDF</button>\n <a href=\"/export/csv\">CSV</a>\n</mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown label=\"Esporta\" variant=\"primary\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Esporta PDF\" icon=\"mi/baseline/picture-as-pdf\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Esporta CSV\" icon=\"mi/baseline/table-chart\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Count on the Default `type` to Submit a Form\n\nUnlike `<mds-button>`, the component defaults to `type=\"button\"`: inside a form, the primary action submits nothing until you set `type=\"submit\"`.\n\n```html\n<!-- INCORRECT: the primary action does not submit -->\n<form action=\"/mail\" method=\"post\">\n <mds-button-dropdown name=\"action\" value=\"send\" label=\"Invia\">\n <mds-button name=\"action\" value=\"draft\" variant=\"dark\" tone=\"text\" label=\"Salva come bozza\"></mds-button>\n </mds-button-dropdown>\n</form>\n\n<!-- CORRECT -->\n<form action=\"/mail\" method=\"post\">\n <mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\">\n <mds-button name=\"action\" value=\"draft\" variant=\"dark\" tone=\"text\" label=\"Salva come bozza\"></mds-button>\n </mds-button-dropdown>\n</form>\n```\n\n#### Do Not Submit the Form from a `click` Listener\n\nA `click` listener on the component also runs for the menu items, whose clicks bubble to it: picking a menu item that submits (\"Salva come bozza\") submits the form twice, once with its `name` / `value` and once without, and the receiver cannot tell which action was chosen. Use `type=\"submit\"` with `name` / `value`.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown id=\"send\" label=\"Invia\"></mds-button-dropdown>\n<script>\n document.getElementById('send').addEventListener('click', () => form.requestSubmit());\n</script>\n\n<!-- CORRECT -->\n<mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\"></mds-button-dropdown>\n```\n\n#### Do Not Listen to `click` for the Primary Action\n\nA `click` on the component also comes from the menu items, whose clicks bubble to it: the primary action would run whenever the user picks an entry of the menu. Listen for `mdsButtonDropdownClick`, which only the primary action emits.\n\n```js\n// INCORRECT: also runs for \"Salva come copia\"\ndropdown.addEventListener('click', () => save());\n\n// CORRECT\ndropdown.addEventListener('mdsButtonDropdownClick', () => save());\n```\n\n#### Do Not Leave a Menu Item That Must Not Submit on the Default `type`\n\nThe menu items are slotted `<mds-button>`, whose `type` defaults to `'submit'`: inside a form, an item that runs your own code (a preview, a copy) submits the form too. Give it `type=\"button\"`.\n\n```html\n<!-- INCORRECT: \"Anteprima\" submits the form -->\n<mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Anteprima\"></mds-button>\n</mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\">\n <mds-button type=\"button\" variant=\"dark\" tone=\"text\" label=\"Anteprima\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Use Unsupported `tone` Values\n\n`<mds-button-dropdown>` accepts `ToneMinimalVariantType`, which is `strong` and `weak` only. Passing `outline`, `text`, or `box` is not valid for this component: the value reaches the internal buttons unchecked, without the split-button styling that only `strong` and `weak` have.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown label=\"Azione\" variant=\"primary\" tone=\"outline\"></mds-button-dropdown>\n<mds-button-dropdown label=\"Azione\" variant=\"primary\" tone=\"text\"></mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown label=\"Azione\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione\"></mds-button>\n</mds-button-dropdown>\n<mds-button-dropdown label=\"Azione\" variant=\"primary\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Try to Customize the Chevron Icon\n\nThe chevron trigger icon is internal and fixed. There is no prop to change it. Do not attempt to override it with CSS property hacks or shadow-DOM selectors.\n\n```css\n/* INCORRECT */\nmds-button-dropdown .dropdown-action mds-icon {\n content: url('custom-arrow.svg');\n}\n\n/* CORRECT - style only through documented custom properties and the dropdown part */\nmds-button-dropdown {\n --mds-button-dropdown-radius: var(--magma-radius-md);\n}\nmds-button-dropdown::part(dropdown) {\n box-shadow: var(--shadow-lg);\n}\n```\n\n#### Do Not Set Boolean Attributes to `\"false\"`\n\n`await`, `disabled`, and `active` are boolean attributes and `mds-button-dropdown` is form-associated: as on a native control, any value turns them on, `\"false\"` included, so this markup renders a disabled button that is waiting. Remove the attribute to turn it off.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown label=\"Invia\" await=\"false\" disabled=\"false\" variant=\"primary\"></mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown label=\"Invia\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Invia come bozza\"></mds-button>\n</mds-button-dropdown>\n```\n"
5269
5508
  },
5270
5509
  "props": [
@@ -5340,6 +5579,47 @@
5340
5579
  "getter": false,
5341
5580
  "setter": false
5342
5581
  },
5582
+ {
5583
+ "name": "current",
5584
+ "type": "\"page\" | \"section\" | boolean | undefined",
5585
+ "complexType": {
5586
+ "original": "ButtonCurrentType",
5587
+ "resolved": "\"page\" | \"section\" | boolean | undefined",
5588
+ "references": {
5589
+ "ButtonCurrentType": {
5590
+ "location": "import",
5591
+ "path": "@type/button",
5592
+ "id": "src/type/button.ts::ButtonCurrentType",
5593
+ "referenceLocation": "ButtonCurrentType"
5594
+ }
5595
+ }
5596
+ },
5597
+ "mutable": false,
5598
+ "attr": "current",
5599
+ "reflectToAttr": true,
5600
+ "docs": "Marks the primary action as the one that leads to the view you are in, as `current` does on\n`mds-button`: `current` (or `current=\"page\"`) is that view, and the primary action neither\nnavigates nor submits nor emits `mdsButtonDropdownClick`; `current=\"section\"` is a view inside\nit, and the primary action stays a link back. Both halves take the look; only the primary\naction is announced with `aria-current`, the chevron keeps opening the menu",
5601
+ "docsTags": [],
5602
+ "values": [
5603
+ {
5604
+ "value": "page",
5605
+ "type": "string"
5606
+ },
5607
+ {
5608
+ "value": "section",
5609
+ "type": "string"
5610
+ },
5611
+ {
5612
+ "type": "boolean"
5613
+ },
5614
+ {
5615
+ "type": "undefined"
5616
+ }
5617
+ ],
5618
+ "optional": true,
5619
+ "required": false,
5620
+ "getter": false,
5621
+ "setter": false
5622
+ },
5343
5623
  {
5344
5624
  "name": "disabled",
5345
5625
  "type": "boolean | undefined",
@@ -5403,7 +5683,59 @@
5403
5683
  "mutable": true,
5404
5684
  "attr": "icon",
5405
5685
  "reflectToAttr": true,
5406
- "docs": "The icon displayed in the button",
5686
+ "docs": "The icon displayed in the button; `iconCurrent` and `iconHover` take its place in their\nstates",
5687
+ "docsTags": [],
5688
+ "values": [
5689
+ {
5690
+ "type": "string"
5691
+ },
5692
+ {
5693
+ "type": "undefined"
5694
+ }
5695
+ ],
5696
+ "optional": true,
5697
+ "required": false,
5698
+ "getter": false,
5699
+ "setter": false
5700
+ },
5701
+ {
5702
+ "name": "iconCurrent",
5703
+ "type": "string | undefined",
5704
+ "complexType": {
5705
+ "original": "string",
5706
+ "resolved": "string | undefined",
5707
+ "references": {}
5708
+ },
5709
+ "mutable": false,
5710
+ "attr": "icon-current",
5711
+ "reflectToAttr": false,
5712
+ "docs": "The icon of the primary action when it is current, in place of `icon`, as `iconCurrent` does\non `mds-button`: under the pointer too, unless `iconHover` says otherwise. Without `icon` it\nshows nothing",
5713
+ "docsTags": [],
5714
+ "values": [
5715
+ {
5716
+ "type": "string"
5717
+ },
5718
+ {
5719
+ "type": "undefined"
5720
+ }
5721
+ ],
5722
+ "optional": true,
5723
+ "required": false,
5724
+ "getter": false,
5725
+ "setter": false
5726
+ },
5727
+ {
5728
+ "name": "iconHover",
5729
+ "type": "string | undefined",
5730
+ "complexType": {
5731
+ "original": "string",
5732
+ "resolved": "string | undefined",
5733
+ "references": {}
5734
+ },
5735
+ "mutable": false,
5736
+ "attr": "icon-hover",
5737
+ "reflectToAttr": false,
5738
+ "docs": "The icon of the primary action under the pointer, in place of `icon`, and `iconCurrent` when\nit is not set, as `iconHover` does on `mds-button`. Without `icon` it shows nothing",
5407
5739
  "docsTags": [],
5408
5740
  "values": [
5409
5741
  {
@@ -5850,8 +6182,8 @@
5850
6182
  "mds-dropdown"
5851
6183
  ],
5852
6184
  "mds-button": [
5853
- "mds-spinner",
5854
6185
  "mds-icon",
6186
+ "mds-spinner",
5855
6187
  "mds-text"
5856
6188
  ]
5857
6189
  },
@@ -5874,8 +6206,8 @@
5874
6206
  }
5875
6207
  ],
5876
6208
  "usage": {
5877
- "1. Description": "The `<mds-button-group>` web component is a layout container of the Magma Design System that clusters related `<mds-button>` controls into a single, evenly-spaced horizontal group such as toolbars, action bars, or segmented sets of actions. It is a presentation-only wrapper with no props, events, or state - its sole job is to arrange its slotted children consistently.\n\n#### Semantic Behavior\n\n- **Default slot is content**: Whatever buttons (or button-like controls) you place inside are projected in source order. The group joins its `<mds-button>` / `<mds-button-dropdown>` members: it flattens their inner corners and sets them 2px apart, so only the outer corners of the cluster stay rounded.\n- **Inline layout**: The group shrinks to fit its content with consistent spacing and stays inline with surrounding elements rather than spanning the full row width.\n- **No own semantics**: It exposes no role, ARIA attributes, form association, focus management, or keyboard handling of its own - accessibility and interaction live entirely in the slotted children. It is purely a visual grouping primitive.\n\n#### Properties & Visual Configurations\n\nThis component has no configurable properties. Visual outcome is determined entirely by the slotted children - typically a set of `<mds-button>` elements sharing a common `variant` / `tone` (see the shared ladder in [`agents/variants.md`](../../../../agents/variants.md)) so the group reads as a cohesive cluster of actions.\n",
5878
- "2. Examples": "Correct and idiomatic ways to use the `<mds-button-group>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Toolbar of Icon-Only Actions\n\nThe primary use case. Group icon-only `<mds-button>` elements that act on the same target - a text selection, a table row, or an editor surface. Each button must carry an explicit `aria-label` because no visible label is present.\n\n```html\n<mds-button-group>\n <mds-button icon=\"mi/baseline/format-bold\" aria-label=\"Grassetto\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-italic\" aria-label=\"Corsivo\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-underlined\" aria-label=\"Sottolineato\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-button-group>\n```\n\n#### Segmented Set of Labelled Actions\n\nUse labelled buttons when the actions benefit from visible text - for example a primary / secondary / destructive trio at the bottom of a form section.\n\n```html\n<mds-button-group>\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n</mds-button-group>\n```\n\n#### Mixed Emphasis Within a Group\n\nPair a high-emphasis primary button with lower-emphasis supporting actions. Keep the same `variant` family and vary only the `tone` so the group reads as a cohesive cluster, not a random set of buttons.\n\n```html\n<mds-button-group>\n <mds-button label=\"Pubblica\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button label=\"Salva come bozza\" variant=\"primary\" tone=\"outline\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-button-group>\n```\n\n#### Inside a Toolbar or Action Bar\n\n`<mds-button-group>` is `inline-flex` by default, so multiple groups sit naturally beside other inline controls in a toolbar without extra CSS.\n\n```html\n<div class=\"toolbar\">\n <mds-button-group>\n <mds-button icon=\"mi/baseline/undo\" aria-label=\"Annulla\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/redo\" aria-label=\"Ripristina\" variant=\"dark\" tone=\"text\"></mds-button>\n </mds-button-group>\n\n <mds-button-group>\n <mds-button icon=\"mi/baseline/format-bold\" aria-label=\"Grassetto\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-italic\" aria-label=\"Corsivo\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-underlined\" aria-label=\"Sottolineato\" variant=\"dark\" tone=\"text\"></mds-button>\n </mds-button-group>\n</div>\n```\n\n#### Including a `<mds-button-dropdown>` in the Group\n\nThe default slot accepts any `<mds-button>` or `<mds-button-dropdown>` sibling component. Place the dropdown last or first depending on visual priority.\n\n```html\n<mds-button-group>\n <mds-button label=\"Esporta CSV\" variant=\"primary\" tone=\"weak\"></mds-button>\n <mds-button-dropdown label=\"Altre opzioni\" variant=\"primary\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Esporta PDF\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Esporta Excel\"></mds-button>\n </mds-button-dropdown>\n</mds-button-group>\n```\n\n#### Disabled Buttons Inside a Group\n\nDisable individual buttons with the `disabled` boolean attribute. Never use `disabled=\"false\"` - remove the attribute to re-enable. The group itself has no `disabled` prop.\n\n```html\n<mds-button-group>\n <mds-button label=\"Approva\" variant=\"success\" tone=\"strong\"></mds-button>\n <mds-button label=\"Rifiuta\" variant=\"error\" tone=\"outline\" disabled></mds-button>\n</mds-button-group>\n```\n",
6209
+ "1. Description": "The `<mds-button-group>` web component is a layout container of the Magma Design System that clusters related `<mds-button>` controls into a single, evenly-spaced horizontal group such as toolbars, action bars, or segmented sets of actions. It is a presentation-only wrapper with no props, events, or state - its sole job is to arrange its slotted children consistently.\n\n#### Semantic Behavior\n\n- **Default slot is content**: Whatever buttons (or button-like controls) you place inside are projected in source order. The group joins its `<mds-button>` / `<mds-button-dropdown>` members: it flattens their inner corners and sets them 2px apart, so only the outer corners of the cluster stay rounded.\n- **Inline layout**: The group shrinks to fit its content with consistent spacing and stays inline with surrounding elements; on its own it never takes the full row width.\n- **Width in a stretched row**: A row that stretches the group, as `actions/stacked` does under `--magma-container-actions` (380px) in `<mds-card-footer>`, `<mds-banner>`, `<mds-status-bar>` or a row of your own (`align-self: stretch`, a `width`, a `flex-basis`), gets the cluster across the whole row, as every other labelled action of it: each labelled member keeps its own width plus the same share of the free width, its label in the middle, so a long label is never cut for a short one; an `<mds-button-dropdown>` member gives its share to its primary action, and an icon-only member keeps its size.\n- **No own semantics**: It exposes no role, ARIA attributes, form association, focus management, or keyboard handling of its own - accessibility and interaction live entirely in the slotted children. It is purely a visual grouping primitive.\n\n#### Properties & Visual Configurations\n\nThis component has no configurable properties. Visual outcome is determined entirely by the slotted children - typically a set of `<mds-button>` elements sharing a common `variant` / `tone` (see the shared ladder in [`agents/variants.md`](../../../../agents/variants.md)) so the group reads as a cohesive cluster of actions.\n",
6210
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-button-group>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Toolbar of Icon-Only Actions\n\nThe primary use case. Group icon-only `<mds-button>` elements that act on the same target - a text selection, a table row, or an editor surface. Each button must carry an explicit `aria-label` because no visible label is present.\n\n```html\n<mds-button-group>\n <mds-button icon=\"mi/baseline/format-bold\" aria-label=\"Grassetto\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-italic\" aria-label=\"Corsivo\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-underlined\" aria-label=\"Sottolineato\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-button-group>\n```\n\n#### Segmented Set of Labelled Actions\n\nUse labelled buttons when the actions benefit from visible text - for example a primary / secondary / destructive trio at the bottom of a form section.\n\n```html\n<mds-button-group>\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n</mds-button-group>\n```\n\n#### Mixed Emphasis Within a Group\n\nPair a high-emphasis primary button with lower-emphasis supporting actions. Keep the same `variant` family and vary only the `tone` so the group reads as a cohesive cluster, not a random set of buttons.\n\n```html\n<mds-button-group>\n <mds-button label=\"Pubblica\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button label=\"Salva come bozza\" variant=\"primary\" tone=\"outline\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-button-group>\n```\n\n#### Inside a Toolbar or Action Bar\n\n`<mds-button-group>` is `inline-flex` by default, so multiple groups sit naturally beside other inline controls in a toolbar without extra CSS.\n\n```html\n<div class=\"toolbar\">\n <mds-button-group>\n <mds-button icon=\"mi/baseline/undo\" aria-label=\"Annulla\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/redo\" aria-label=\"Ripristina\" variant=\"dark\" tone=\"text\"></mds-button>\n </mds-button-group>\n\n <mds-button-group>\n <mds-button icon=\"mi/baseline/format-bold\" aria-label=\"Grassetto\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-italic\" aria-label=\"Corsivo\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-underlined\" aria-label=\"Sottolineato\" variant=\"dark\" tone=\"text\"></mds-button>\n </mds-button-group>\n</div>\n```\n\n#### Including a `<mds-button-dropdown>` in the Group\n\nThe default slot accepts any `<mds-button>` or `<mds-button-dropdown>` sibling component. Place the dropdown last or first depending on visual priority.\n\n```html\n<mds-button-group>\n <mds-button label=\"Esporta CSV\" variant=\"primary\" tone=\"weak\"></mds-button>\n <mds-button-dropdown label=\"Altre opzioni\" variant=\"primary\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Esporta PDF\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Esporta Excel\"></mds-button>\n </mds-button-dropdown>\n</mds-button-group>\n```\n\n#### In a Row of Actions That Stacks\n\nStretch the group as any other action of the row: under `--magma-container-actions` of its container (`@max-actions:`), `actions/stacked` puts every labelled action at the full width, and the group shares that width among its labelled members, the joined corners as before. No part or custom property is needed.\n\n```html\n<div class=\"@container\">\n <div class=\"flex justify-end gap-inline @max-actions:flex-col @max-actions:*:self-stretch\">\n <mds-button variant=\"dark\" tone=\"outline\" label=\"Annulla\"></mds-button>\n <mds-button-group>\n <mds-button variant=\"primary\" tone=\"outline\" label=\"Salva come bozza\"></mds-button>\n <mds-button variant=\"primary\" label=\"Pubblica\"></mds-button>\n </mds-button-group>\n </div>\n</div>\n```\n\n#### Disabled Buttons Inside a Group\n\nDisable individual buttons with the `disabled` boolean attribute. Never use `disabled=\"false\"` - remove the attribute to re-enable. The group itself has no `disabled` prop.\n\n```html\n<mds-button-group>\n <mds-button label=\"Approva\" variant=\"success\" tone=\"strong\"></mds-button>\n <mds-button label=\"Rifiuta\" variant=\"error\" tone=\"outline\" disabled></mds-button>\n</mds-button-group>\n```\n",
5879
6211
  "3. Mistakes": "Common incorrect uses of `<mds-button-group>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Nest Raw `<button>` Elements Inside the Group\n\nThe group is part of the Magma component system and is designed to host `<mds-button>` (and sibling `mds-*` action) components. Raw `<button>` elements bypass theming, focus styles, and accessibility defaults.\n\n```html\n<!-- INCORRECT -->\n<mds-button-group>\n <button class=\"btn\">Salva</button>\n <button class=\"btn\">Annulla</button>\n</mds-button-group>\n\n<!-- CORRECT -->\n<mds-button-group>\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n</mds-button-group>\n```\n\n#### Do Not Wrap the Group in an Anchor\n\n`<mds-button-group>` contains interactive controls; nesting the whole group inside `<a>` creates nested interactives, breaks keyboard semantics, and fails accessibility audits. Use the `href` prop on individual `<mds-button>` elements instead.\n\n```html\n<!-- INCORRECT -->\n<a href=\"/azioni\">\n <mds-button-group>\n <mds-button label=\"Vai\" variant=\"primary\"></mds-button>\n </mds-button-group>\n</a>\n\n<!-- CORRECT -->\n<mds-button-group>\n <mds-button label=\"Vai\" href=\"/azioni\" variant=\"primary\"></mds-button>\n</mds-button-group>\n```\n\n#### Do Not Omit `aria-label` on Icon-Only Buttons Inside a Group\n\nGrouping icon-only buttons does not remove the requirement for an accessible name on each child. Without it `mds-button` falls back to the last segment of the icon slug (\"undo\"), which names the icon, not the action.\n\n```html\n<!-- INCORRECT -->\n<mds-button-group>\n <mds-button icon=\"mi/baseline/undo\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/redo\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-button-group>\n\n<!-- CORRECT -->\n<mds-button-group>\n <mds-button icon=\"mi/baseline/undo\" aria-label=\"Annulla\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/redo\" aria-label=\"Ripristina\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-button-group>\n```\n\n#### Do Not Nest `<mds-button-group>` Inside Another Group\n\nThe component is a flat layout primitive; nesting groups creates redundant flex containers that break the consistent spacing and group visual coherence. Keep the hierarchy flat.\n\n```html\n<!-- INCORRECT -->\n<mds-button-group>\n <mds-button-group>\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button label=\"Bozza\" variant=\"primary\" tone=\"outline\"></mds-button>\n </mds-button-group>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-button-group>\n\n<!-- CORRECT -->\n<mds-button-group>\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button label=\"Bozza\" variant=\"primary\" tone=\"outline\"></mds-button>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-button-group>\n```\n\n#### Do Not Override Spacing with Inline Styles\n\nThe component manages its own gap via a design-token-backed CSS value. Setting inline `gap`, `margin`, or `padding` on the host or child buttons breaks the token contract and may produce inconsistent spacing across themes.\n\n```css\n/* INCORRECT */\nmds-button-group {\n gap: 16px;\n}\nmds-button-group mds-button {\n margin-right: 8px;\n}\n\n/* CORRECT - let the component handle spacing; style only what it exposes */\nmds-button-group {\n /* no gap or margin overrides needed */\n}\n```\n"
5880
6212
  },
5881
6213
  "props": [],
@@ -5913,11 +6245,49 @@
5913
6245
  }
5914
6246
  ],
5915
6247
  "usage": {
5916
- "1. Description": "The `<mds-calendar>` web component is the date-selection surface of the Magma Design System: a localized month grid that lets users pick either a single day or a date range. It is the visual engine behind `mds-input-date` and `mds-input-date-range`.\n\n#### Semantic Behavior\n\n- **Range vs. single mode**: range selection is the default; set `singlePicker` to pick one day. In range mode the first click sets the start, the second sets the end, and a third click starts a new range from the clicked day; in single mode each click replaces the prior choice.\n- **Range auto-ordering**: If the second click lands before the current start, the two endpoints are swapped so `startDate` always precedes `endDate`; a `startDate` / `endDate` pair given backwards, in the markup or from code, is put in order the same way (with a console warning).\n- **Hover preview**: While a range start is set, hovering over cells previews the candidate range live (range mode only).\n- **Min/max bounds**: `min` and `max` mark out-of-range day cells as disabled, blocking their selection.\n- **Multi-view navigation**: The header toggles between the day grid, a month picker, and a year picker; the year view pages in decades while the calendar view pages month by month. The two arrows are icon-only buttons named in the page language (the `lang` of `<html>`): previous / next month on the day grid, previous / next years in the year view; the month picker has nothing to page through, so there they are disabled.\n- **Localization**: Weekday names, month names, and cell titles are formatted in the page language (the `lang` attribute of `<html>`, `en` when absent).\n- **Emitted events**: `mdsCalendarChange` fires on every pick with `{ startDate, endDate? }`: in range mode the first click emits `{ startDate }` alone, the second the full range; `mdsCalendarPreselect` fires only with a completed range, to let preselection shortcuts re-evaluate their state.\n- **Preselection slot**: A `preselection` named slot hosts quick-pick shortcuts. The area appears while the slot holds an element, one added after load included; `hidePreselection` collapses it. The `date-preselection--has-preselection` class earlier versions required is no longer needed (it still shows the area).\n\n#### Properties & Visual Configurations\n\nDates are exchanged as ISO 8601 strings (`YYYY-MM-DD`). `startDate` and `endDate` seed the selection (a click updates the internal selection and emits `mdsCalendarChange`, it does not rewrite the attributes); on load, a valid `startDate` also determines which month is shown first.\n\n- **`singlePicker`** is the mode switch: omit it for two-ended range selection, set it for single-day pickers. When set, any `endDate` is ignored and cleared with a warning.\n- **`hidePreviousButton`** / **`hideNextButton`** remove one of the header navigation buttons, typically on calendars paired side by side; **`disableMonthYearSelection`** keeps the header on the day grid; **`hideToday`** removes the highlight on today's date.\n- Every boolean prop defaults to `false`: the feature is on until the bare attribute turns it off.\n- **`min`** / **`max`** define the selectable window; days outside it render disabled rather than being hidden.\n\nThis component does not use the shared `variant` / `tone` ladders on its host - those are defined in [`agents/variants.md`](../../../../agents/variants.md) and are applied internally to the navigation buttons it renders.\n",
5917
- "2. Examples": "Correct and idiomatic ways to use the `<mds-calendar>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Single-Day Picker\n\nSet the bare `single-picker` attribute for a plain single-date selector. `mdsCalendarChange` fires once with `{ startDate }` and no `endDate`. Seed an initial date via `start-date`.\n\n```html\n<mds-calendar single-picker start-date=\"2025-06-10\"></mds-calendar>\n\n<script>\n document.querySelector('mds-calendar').addEventListener('mdsCalendarChange', (e) => {\n console.log('Data selezionata:', e.detail.startDate);\n });\n</script>\n```\n\n#### Range Picker (default mode)\n\nRange selection is the default: omit `single-picker`. The first click sets the start date, the second sets the end date. A third click starts a new range from the clicked day. `mdsCalendarChange` fires on both clicks: after the first one `endDate` is absent. Preload a range by supplying both `start-date` and `end-date`.\n\n```html\n<mds-calendar start-date=\"2025-09-01\" end-date=\"2025-09-15\"></mds-calendar>\n\n<script>\n document.querySelector('mds-calendar').addEventListener('mdsCalendarChange', (e) => {\n const { startDate, endDate } = e.detail;\n console.log('Intervallo selezionato:', startDate, '-', endDate);\n });\n</script>\n```\n\n#### Restricting the Selectable Window with `min` / `max`\n\nPass ISO 8601 strings to `min` and `max` to mark out-of-range days as disabled. Days outside the window are not hidden - they remain visible but cannot be clicked.\n\n```html\n<mds-calendar\n single-picker\n min=\"2025-01-01\"\n max=\"2025-12-31\"\n></mds-calendar>\n```\n\n#### Navigating to a Specific Month Programmatically\n\nUse the `updateCurrentDate` method to jump the visible month without changing the current selection. Pass any ISO date string that falls within the target month.\n\n```html\n<mds-calendar id=\"cal\" single-picker></mds-calendar>\n\n<script>\n document.querySelector('#cal').updateCurrentDate('2026-03-01');\n</script>\n```\n\n#### Quick-Pick Preselection Shortcuts\n\nThe `preselection` named slot hosts your own shortcuts, for example `mds-button` elements whose `click` sets `start-date` / `end-date` ([`mds-input-date-range-preselection`](../mds-input-date-range-preselection/AGENTS.md) works only inside `mds-input-date-range`). The slot panel becomes visible as soon as the slot holds an element, also one added after load; set `hide-preselection` to keep it collapsed. `mdsCalendarPreselect` fires after each completed range selection so the shortcuts can re-evaluate their active state.\n\n```html\n<mds-calendar start-date=\"2025-09-01\" end-date=\"2025-09-07\">\n <div slot=\"preselection\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Ultimi 7 giorni\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Ultimi 30 giorni\"></mds-button>\n </div>\n</mds-calendar>\n```\n\n#### Paired Calendars Without Duplicate Navigation\n\nTwo calendars shown side by side (the pattern used by `mds-input-date-range` on wide viewports) should expose one previous and one next button in total: hide the inner buttons with `hide-previous-button` / `hide-next-button` and lock the header on the day grid with `disable-month-year-selection`, then keep the two `view-date` values one month apart from the `mdsCalendarNavigate` event.\n\n```html\n<mds-calendar id=\"start\" view-date=\"2025-09-01\" hide-next-button disable-month-year-selection></mds-calendar>\n<mds-calendar id=\"end\" view-date=\"2025-10-01\" hide-previous-button disable-month-year-selection></mds-calendar>\n```\n\n#### Listening for Selection Changes\n\nListen on the documented `mdsCalendarChange` event - not the native `change` event - so the handler receives the structured `{ startDate, endDate? }` detail object directly from the Shadow DOM.\n\n```html\n<mds-calendar id=\"picker\" single-picker></mds-calendar>\n\n<script>\n document.querySelector('#picker').addEventListener('mdsCalendarChange', (e) => {\n const { startDate } = e.detail;\n document.querySelector('#output').textContent = 'Scadenza: ' + startDate;\n });\n</script>\n```\n\n#### Embedded inside `mds-input-date` or `mds-input-date-range`\n\n`<mds-calendar>` is the visual engine used internally by [`mds-input-date`](../mds-input-date/AGENTS.md) and [`mds-input-date-range`](../mds-input-date-range/AGENTS.md). In most product surfaces, reach for those higher-level components. Use `<mds-calendar>` directly only when you need a standalone always-visible date grid without an associated text input.\n\n```html\n<!-- Higher-level: input with calendar overlay -->\n<mds-input-field label=\"Scadenza\">\n <mds-input-date name=\"scadenza\"></mds-input-date>\n</mds-input-field>\n\n<!-- Lower-level: always-visible standalone grid -->\n<mds-calendar single-picker></mds-calendar>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nAdjust the calendar appearance only through the public `--mds-calendar-*` CSS custom properties. Set them on the host element or a parent selector; use the semantic color roles so dark mode, named themes and high contrast keep working. The day cells inherit from the calendar their own public `--mds-calendar-cell-*` properties, documented on [`mds-calendar-cell`](../mds-calendar-cell/AGENTS.md).\n\n```css\n.booking-widget mds-calendar {\n --mds-calendar-background: rgb(var(--magma-surface-muted));\n --mds-calendar-border-radius: var(--magma-radius-xl);\n --mds-calendar-padding: calc(var(--spacing) * 500);\n --mds-calendar-cell-other-month-visibility: hidden;\n}\n```\n",
5918
- "3. Mistakes": "Common incorrect uses of `<mds-calendar>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Toggle Single Mode with a Quoted Boolean String\n\n`singlePicker` is a boolean prop that defaults to `false`. The component reads the string `\"false\"` as `false`, but the prop is not reflected, so `single-picker=\"false\"` stays in the DOM and attribute selectors (`mds-calendar[single-picker]`) and any code reading the attribute still see it set. Use the bare attribute for single mode and omit it for the default range mode; toggle it at runtime by adding/removing the attribute or setting the property in JavaScript.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar single-picker=\"false\"></mds-calendar>\n\n<!-- CORRECT -->\n<mds-calendar></mds-calendar>\n<mds-calendar id=\"cal\" single-picker></mds-calendar>\n<script>\n document.querySelector('#cal').singlePicker = false; // back to range mode\n</script>\n```\n\n#### Do Not Set `end-date` When `single-picker` Is Set\n\nWhen `singlePicker` is set, the component rejects `endDate` with a console warning and clears it internally. Setting both `single-picker` and `end-date` is contradictory and produces no visible selection for the end date.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar single-picker start-date=\"2025-06-01\" end-date=\"2025-06-15\"></mds-calendar>\n\n<!-- CORRECT -->\n<mds-calendar single-picker start-date=\"2025-06-01\"></mds-calendar>\n```\n\n#### Do Not Provide `startDate` After `endDate`\n\nDates must be chronologically ordered: `startDate` must precede `endDate`. The component does not reorder them: set at load, the two ends are marked with no range between them; changed later, it only logs a console warning. Always ensure `start-date <= end-date`.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar start-date=\"2025-12-31\" end-date=\"2025-12-01\"></mds-calendar>\n\n<!-- CORRECT -->\n<mds-calendar start-date=\"2025-12-01\" end-date=\"2025-12-31\"></mds-calendar>\n```\n\n#### Do Not Listen for the Native `change` Event\n\n`<mds-calendar>` does not bubble a native `change` event from inside its Shadow DOM. Use the documented `mdsCalendarChange` custom event so the handler reliably receives the structured `{ startDate, endDate? }` payload.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar id=\"cal\"></mds-calendar>\n<script>\n document.querySelector('#cal').addEventListener('change', (e) => {\n console.log(e.target.value); // undefined - wrong event\n });\n</script>\n\n<!-- CORRECT -->\n<mds-calendar id=\"cal\"></mds-calendar>\n<script>\n document.querySelector('#cal').addEventListener('mdsCalendarChange', (e) => {\n console.log(e.detail.startDate, e.detail.endDate);\n });\n</script>\n```\n\n#### Do Not Use `<mds-calendar>` as a Drop-In Replacement for `mds-input-date`\n\n`<mds-calendar>` is not form-associated and emits no `name`/`value` pair for form submission. When you need a date picker tied to a form field, use [`mds-input-date`](../mds-input-date/AGENTS.md) (single date) or [`mds-input-date-range`](../mds-input-date-range/AGENTS.md) (range) instead.\n\n```html\n<!-- INCORRECT -->\n<form action=\"/prenota\" method=\"post\">\n <mds-calendar name=\"check-in\" single-picker></mds-calendar>\n <mds-button type=\"submit\" label=\"Prenota\"></mds-button>\n</form>\n\n<!-- CORRECT -->\n<form action=\"/prenota\" method=\"post\">\n <mds-input-field label=\"Data di arrivo\">\n <mds-input-date name=\"check-in\"></mds-input-date>\n </mds-input-field>\n <mds-button type=\"submit\" label=\"Prenota\"></mds-button>\n</form>\n```\n\n#### Do Not Style Internals via Undocumented `::part()` Selectors\n\nThe only supported customization surface is the set of public `--mds-calendar-*` CSS custom properties. Targeting shadow-DOM internals with `::part()` selectors that are not in the documentation couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-calendar::part(nav) {\n background: red;\n}\nmds-calendar::part(cell) {\n border: 1px solid blue;\n}\n\n/* CORRECT */\nmds-calendar {\n --mds-calendar-background: rgb(var(--magma-surface-muted));\n --mds-calendar-border-radius: var(--magma-radius-xl);\n --mds-calendar-cell-other-month-visibility: hidden;\n}\n```\n"
6248
+ "1. Description": "The `<mds-calendar>` web component is the date-selection surface of the Magma Design System: a localized month grid that lets users pick either a single day or a date range. It is the visual engine behind `mds-input-date` and `mds-input-date-range`.\n\n#### Semantic Behavior\n\n- **Range vs. single mode**: range selection is the default; set `singlePicker` to pick one day. In range mode the first click sets the start, the second sets the end, and a third click starts a new range from the clicked day; in single mode each click replaces the prior choice.\n- **Active end**: a parent that lets the user choose which end to change, as [`mds-input-date-range`](../mds-input-date-range/AGENTS.md) does, names it in `activeEnd` (`start` or `end`): a click then changes that end only, also on a complete range, instead of starting a new one. With no start, a click picks the start whatever `activeEnd` says.\n- **Never backwards**: a click never swaps the ends. A day before the start, clicked while the end is picked, becomes the new start and the end is still to pick; a day after the end, clicked while the start is picked (`activeEnd=\"start\"`), becomes the new start and the end is emptied. A `startDate` / `endDate` pair given backwards, in the markup or from code, is put in order (with a console warning); a parent that sets the two props one after the other is read once both have arrived, so a start moved past the old end is not taken for a range given backwards.\n- **Hover preview**: While a range waits for its end, the day under the pointer is previewed: the band from the start to that day when a click there would end the range, that day alone when it would become a new start. The preview is dropped with the click that changes the range.\n- **Marks**: a chosen day, either end of a range or the day of a single picker, is a full dot, the start and the end alike, and the days between them a band; the day under the pointer, not chosen yet, is a ring on a paler band.\n- **Min/max bounds**: `min` and `max` mark out-of-range day cells as disabled, blocking their selection.\n- **Multi-view navigation**: The header toggles between the day grid, a month picker, and a year picker; the year view pages in decades while the calendar view pages month by month. The two arrows are icon-only buttons named in the page language (the `lang` of `<html>`): previous / next month on the day grid, previous / next years in the year view; the month picker has nothing to page through, so there they are disabled. The header is a navigation landmark named after the month and year it shows, so two calendars side by side are two distinct landmarks.\n- **Localization**: Weekday names, month names, and cell titles are formatted in the page language (the `lang` attribute of `<html>`, `en` when absent).\n- **Emitted events**: `mdsCalendarChange` fires on every pick with `{ startDate, endDate? }`: in range mode the first click emits `{ startDate }` alone, the second the full range; `mdsCalendarPreselect` fires only with a completed range, to let preselection shortcuts re-evaluate their state.\n- **Preselection slot**: A `preselection` named slot hosts quick-pick shortcuts. The area appears while the slot holds an element, one added after load included; `hidePreselection` collapses it. The `date-preselection--has-preselection` class earlier versions required is no longer needed (it still shows the area).\n\n#### Properties & Visual Configurations\n\nDates are exchanged as ISO 8601 strings (`YYYY-MM-DD`). `startDate` and `endDate` seed the selection (a click updates the internal selection and emits `mdsCalendarChange`, it does not rewrite the attributes); on load, a valid `startDate` also determines which month is shown first.\n\n- **`singlePicker`** is the mode switch: omit it for two-ended range selection, set it for single-day pickers. When set, any `endDate` is ignored and cleared with a warning.\n- **`activeEnd`** names the end the next click picks, for a parent that shows the user which one it is; leave it unset on a calendar standing alone.\n- **`hidePreviousButton`** / **`hideNextButton`** remove one of the header navigation buttons, typically on calendars paired side by side; **`disableMonthYearSelection`** keeps the header on the day grid; **`hideToday`** removes the highlight on today's date.\n- Every boolean prop defaults to `false`: the feature is on until the bare attribute turns it off.\n- **`min`** / **`max`** define the selectable window; days outside it render disabled rather than being hidden.\n\nThis component does not use the shared `variant` / `tone` ladders on its host - those are defined in [`agents/variants.md`](../../../../agents/variants.md) and are applied internally to the navigation buttons it renders.\n",
6249
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-calendar>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Single-Day Picker\n\nSet the bare `single-picker` attribute for a plain single-date selector. `mdsCalendarChange` fires once with `{ startDate }` and no `endDate`. Seed an initial date via `start-date`.\n\n```html\n<mds-calendar single-picker start-date=\"2025-06-10\"></mds-calendar>\n\n<script>\n document.querySelector('mds-calendar').addEventListener('mdsCalendarChange', (e) => {\n console.log('Data selezionata:', e.detail.startDate);\n });\n</script>\n```\n\n#### Range Picker (default mode)\n\nRange selection is the default: omit `single-picker`. The first click sets the start date, the second sets the end date; a second click before the start makes that day the new start, and the end is still to pick. A click on a complete range starts a new range from the clicked day. `mdsCalendarChange` fires on every click: while the end is missing `endDate` is absent. Preload a range by supplying both `start-date` and `end-date`.\n\n```html\n<mds-calendar start-date=\"2025-09-01\" end-date=\"2025-09-15\"></mds-calendar>\n\n<script>\n document.querySelector('mds-calendar').addEventListener('mdsCalendarChange', (e) => {\n const { startDate, endDate } = e.detail;\n console.log('Intervallo selezionato:', startDate, '-', endDate);\n });\n</script>\n```\n\n#### Naming the End a Click Picks\n\nA parent that lets the user choose which end to change sets `active-end` to `start` or `end`, and keeps it in step with what the user picks: a click then changes that end only, also on a complete range. A click never puts the range backwards: picking the end, a day before the start becomes the new start; picking the start, a day after the end becomes the new start and empties the end. [`mds-input-date-range`](../mds-input-date-range/AGENTS.md) drives its calendars this way from its fields and from the header of its panel; prefer it to a calendar of your own.\n\n```html\n<mds-calendar id=\"periodo\" start-date=\"2025-09-01\" end-date=\"2025-09-15\" active-end=\"start\"></mds-calendar>\n\n<script>\n const calendar = document.querySelector('#periodo');\n calendar.addEventListener('mdsCalendarChange', () => {\n // the start is picked: the end comes next\n calendar.activeEnd = 'end';\n });\n</script>\n```\n\n#### Restricting the Selectable Window with `min` / `max`\n\nPass ISO 8601 strings to `min` and `max` to mark out-of-range days as disabled. Days outside the window are not hidden - they remain visible but cannot be clicked.\n\n```html\n<mds-calendar\n single-picker\n min=\"2025-01-01\"\n max=\"2025-12-31\"\n></mds-calendar>\n```\n\n#### Navigating to a Specific Month Programmatically\n\nUse the `updateCurrentDate` method to jump the visible month without changing the current selection. Pass any ISO date string that falls within the target month.\n\n```html\n<mds-calendar id=\"cal\" single-picker></mds-calendar>\n\n<script>\n document.querySelector('#cal').updateCurrentDate('2026-03-01');\n</script>\n```\n\n#### Quick-Pick Preselection Shortcuts\n\nThe `preselection` named slot hosts your own shortcuts, for example `mds-button` elements whose `click` sets `start-date` / `end-date` ([`mds-input-date-range-preselection`](../mds-input-date-range-preselection/AGENTS.md) works only inside `mds-input-date-range`). The slot panel becomes visible as soon as the slot holds an element, also one added after load; set `hide-preselection` to keep it collapsed. `mdsCalendarPreselect` fires after each completed range selection so the shortcuts can re-evaluate their active state.\n\n```html\n<mds-calendar start-date=\"2025-09-01\" end-date=\"2025-09-07\">\n <div slot=\"preselection\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Ultimi 7 giorni\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Ultimi 30 giorni\"></mds-button>\n </div>\n</mds-calendar>\n```\n\n#### Paired Calendars Without Duplicate Navigation\n\nTwo calendars shown side by side (the pattern used by `mds-input-date-range` on wide viewports) should expose one previous and one next button in total: hide the inner buttons with `hide-previous-button` / `hide-next-button` and lock the header on the day grid with `disable-month-year-selection`, then keep the two `view-date` values one month apart from the `mdsCalendarNavigate` event.\n\n```html\n<mds-calendar id=\"start\" view-date=\"2025-09-01\" hide-next-button disable-month-year-selection></mds-calendar>\n<mds-calendar id=\"end\" view-date=\"2025-10-01\" hide-previous-button disable-month-year-selection></mds-calendar>\n```\n\n#### Listening for Selection Changes\n\nListen on the documented `mdsCalendarChange` event - not the native `change` event - so the handler receives the structured `{ startDate, endDate? }` detail object directly from the Shadow DOM.\n\n```html\n<mds-calendar id=\"picker\" single-picker></mds-calendar>\n\n<script>\n document.querySelector('#picker').addEventListener('mdsCalendarChange', (e) => {\n const { startDate } = e.detail;\n document.querySelector('#output').textContent = 'Scadenza: ' + startDate;\n });\n</script>\n```\n\n#### Embedded inside `mds-input-date` or `mds-input-date-range`\n\n`<mds-calendar>` is the visual engine used internally by [`mds-input-date`](../mds-input-date/AGENTS.md) and [`mds-input-date-range`](../mds-input-date-range/AGENTS.md). In most product surfaces, reach for those higher-level components. Use `<mds-calendar>` directly only when you need a standalone always-visible date grid without an associated text input.\n\n```html\n<!-- Higher-level: input with calendar overlay -->\n<mds-input-field label=\"Scadenza\">\n <mds-input-date name=\"scadenza\"></mds-input-date>\n</mds-input-field>\n\n<!-- Lower-level: always-visible standalone grid -->\n<mds-calendar single-picker></mds-calendar>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nAdjust the calendar appearance only through the public `--mds-calendar-*` CSS custom properties. Set them on the host element or a parent selector; use the semantic color roles so dark mode, named themes and high contrast keep working. The day cells inherit from the calendar their own public `--mds-calendar-cell-*` properties, documented on [`mds-calendar-cell`](../mds-calendar-cell/AGENTS.md).\n\n```css\n.booking-widget mds-calendar {\n --mds-calendar-background: rgb(var(--magma-surface-muted));\n --mds-calendar-border-radius: var(--magma-radius-xl);\n --mds-calendar-padding: calc(var(--spacing) * 500);\n --mds-calendar-cell-other-month-visibility: hidden;\n}\n```\n",
6250
+ "3. Mistakes": "Common incorrect uses of `<mds-calendar>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Toggle Single Mode with a Quoted Boolean String\n\n`singlePicker` is a boolean prop that defaults to `false`. The component reads the string `\"false\"` as `false`, but the prop is not reflected, so `single-picker=\"false\"` stays in the DOM and attribute selectors (`mds-calendar[single-picker]`) and any code reading the attribute still see it set. Use the bare attribute for single mode and omit it for the default range mode; toggle it at runtime by adding/removing the attribute or setting the property in JavaScript.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar single-picker=\"false\"></mds-calendar>\n\n<!-- CORRECT -->\n<mds-calendar></mds-calendar>\n<mds-calendar id=\"cal\" single-picker></mds-calendar>\n<script>\n document.querySelector('#cal').singlePicker = false; // back to range mode\n</script>\n```\n\n#### Do Not Set `end-date` When `single-picker` Is Set\n\nWhen `singlePicker` is set, the component rejects `endDate` with a console warning and clears it internally. Setting both `single-picker` and `end-date` is contradictory and produces no visible selection for the end date.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar single-picker start-date=\"2025-06-01\" end-date=\"2025-06-15\"></mds-calendar>\n\n<!-- CORRECT -->\n<mds-calendar single-picker start-date=\"2025-06-01\"></mds-calendar>\n```\n\n#### Do Not Provide `startDate` After `endDate`\n\nDates must be chronologically ordered: `startDate` must precede `endDate`. The component puts a pair given backwards in order, with a console warning, but the warning is noise in the console of the page and the swap may not be the range the user meant. Always ensure `start-date <= end-date`; setting the two one after the other in the same task is fine, the calendar reads them once both have arrived.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar start-date=\"2025-12-31\" end-date=\"2025-12-01\"></mds-calendar>\n\n<!-- CORRECT -->\n<mds-calendar start-date=\"2025-12-01\" end-date=\"2025-12-31\"></mds-calendar>\n```\n\n#### Do Not Listen for the Native `change` Event\n\n`<mds-calendar>` does not bubble a native `change` event from inside its Shadow DOM. Use the documented `mdsCalendarChange` custom event so the handler reliably receives the structured `{ startDate, endDate? }` payload.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar id=\"cal\"></mds-calendar>\n<script>\n document.querySelector('#cal').addEventListener('change', (e) => {\n console.log(e.target.value); // undefined - wrong event\n });\n</script>\n\n<!-- CORRECT -->\n<mds-calendar id=\"cal\"></mds-calendar>\n<script>\n document.querySelector('#cal').addEventListener('mdsCalendarChange', (e) => {\n console.log(e.detail.startDate, e.detail.endDate);\n });\n</script>\n```\n\n#### Do Not Use `<mds-calendar>` as a Drop-In Replacement for `mds-input-date`\n\n`<mds-calendar>` is not form-associated and emits no `name`/`value` pair for form submission. When you need a date picker tied to a form field, use [`mds-input-date`](../mds-input-date/AGENTS.md) (single date) or [`mds-input-date-range`](../mds-input-date-range/AGENTS.md) (range) instead.\n\n```html\n<!-- INCORRECT -->\n<form action=\"/prenota\" method=\"post\">\n <mds-calendar name=\"check-in\" single-picker></mds-calendar>\n <mds-button type=\"submit\" label=\"Prenota\"></mds-button>\n</form>\n\n<!-- CORRECT -->\n<form action=\"/prenota\" method=\"post\">\n <mds-input-field label=\"Data di arrivo\">\n <mds-input-date name=\"check-in\"></mds-input-date>\n </mds-input-field>\n <mds-button type=\"submit\" label=\"Prenota\"></mds-button>\n</form>\n```\n\n#### Do Not Style Internals via Undocumented `::part()` Selectors\n\nThe only supported customization surface is the set of public `--mds-calendar-*` CSS custom properties. Targeting shadow-DOM internals with `::part()` selectors that are not in the documentation couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-calendar::part(nav) {\n background: red;\n}\nmds-calendar::part(cell) {\n border: 1px solid blue;\n}\n\n/* CORRECT */\nmds-calendar {\n --mds-calendar-background: rgb(var(--magma-surface-muted));\n --mds-calendar-border-radius: var(--magma-radius-xl);\n --mds-calendar-cell-other-month-visibility: hidden;\n}\n```\n"
5919
6251
  },
5920
6252
  "props": [
6253
+ {
6254
+ "name": "activeEnd",
6255
+ "type": "\"end\" | \"start\" | undefined",
6256
+ "complexType": {
6257
+ "original": "CalendarRangeEndType",
6258
+ "resolved": "\"end\" | \"start\" | undefined",
6259
+ "references": {
6260
+ "CalendarRangeEndType": {
6261
+ "location": "import",
6262
+ "path": "./meta/types",
6263
+ "id": "src/components/mds-calendar/meta/types.ts::CalendarRangeEndType",
6264
+ "referenceLocation": "CalendarRangeEndType"
6265
+ }
6266
+ }
6267
+ },
6268
+ "mutable": false,
6269
+ "attr": "active-end",
6270
+ "reflectToAttr": true,
6271
+ "docs": "Specifies the end of the range the next click picks, `start` or `end`, for a parent that\nlets the user choose it, as `mds-input-date-range` does from its fields and from the header\nof its panel. A click never puts the range backwards: a day after the end, picked as the\nstart, becomes the new start and empties the end; a day before the start, picked as the end,\nbecomes the new start and leaves the end to pick. With no start, a click picks the start.\nLeft unset, the calendar picks the start, then the end, and a click on a complete range\nstarts a new one.",
6272
+ "docsTags": [],
6273
+ "values": [
6274
+ {
6275
+ "value": "end",
6276
+ "type": "string"
6277
+ },
6278
+ {
6279
+ "value": "start",
6280
+ "type": "string"
6281
+ },
6282
+ {
6283
+ "type": "undefined"
6284
+ }
6285
+ ],
6286
+ "optional": true,
6287
+ "required": false,
6288
+ "getter": false,
6289
+ "setter": false
6290
+ },
5921
6291
  {
5922
6292
  "name": "disableMonthYearSelection",
5923
6293
  "type": "boolean",
@@ -6511,8 +6881,8 @@
6511
6881
  "mds-calendar-cell"
6512
6882
  ],
6513
6883
  "mds-button": [
6514
- "mds-spinner",
6515
6884
  "mds-icon",
6885
+ "mds-spinner",
6516
6886
  "mds-text"
6517
6887
  ],
6518
6888
  "mds-calendar-cell": [
@@ -6540,8 +6910,8 @@
6540
6910
  }
6541
6911
  ],
6542
6912
  "usage": {
6543
- "1. Description": "The `<mds-calendar-cell>` web component represents a single selectable day inside the [`<mds-calendar>`](../mds-calendar/AGENTS.md) grid. It is a presentational child that renders the day number and exposes attributes the parent calendar drives to express the day's role and its position within a selection range.\n\n#### Semantic Behavior\n\n- **Compound child only**: It is rendered only by `<mds-calendar>`, which generates one cell per day of the visible month grid inside its own shadow DOM (the calendar has no default slot): consumers never write it, neither standalone nor as a child of the calendar.\n- **Parent-driven selection**: The cell holds no internal selection state. The parent calendar drives the `date`, `selection` and `preview` attributes to paint range boundaries and intermediate days; the cell only reflects what it is given.\n- **No own events**: Clicks and hover are handled by the parent (range building, preview, and the `mdsCalendarChange` / `mdsCalendarPreselect` events from `<mds-calendar>`). The cell itself emits nothing.\n- **Disabled state**: When `disabled` is set the day cannot be activated; the parent applies this for days outside the calendar's `min`/`max` range.\n- **Today marker**: `today` is a presentational flag the parent sets on the cell matching the current date, used only for styling emphasis.\n\n#### Properties & Visual Configurations\n\nMost props are state mirrors written by the parent rather than knobs a consumer tunes directly.\n\n- **`month`**: Distinguishes how the day relates to the displayed month - `current` for in-month days, `other` for leading/trailing days spilling in from adjacent months. The type also allows `weekend`, which is deprecated: the calendar never sets it and it has no styling of its own, since the weekend color comes from the cell's position (the last two columns of the week).\n- **`selection`**: Marks the cell's position within an active range - `start`, `end`, `middle`, or `single` (a one-day or collapsed range); absence or `none` means unselected. This is what produces the connected range visuals across adjacent cells.\n- **`preview`**: When `true`, the current selection is a transient hover/preview rather than a committed selection, allowing distinct styling while the user is still choosing the second boundary.\n- **`orientation`**: Selection-connector direction. The type allows `horizontal`, `vertical`, and `both`, but only `horizontal` is currently supported.\n- **`date`**: The cell's ISO `YYYY-MM-DD` date; the parent matches against it to compute selection state, so it is required for the cell to participate in range logic.\n",
6544
- "2. Examples": "Correct and idiomatic ways to use the `<mds-calendar-cell>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n`<mds-calendar-cell>` is an internal subpart: its real parent [`<mds-calendar>`](../mds-calendar/AGENTS.md) renders one cell per day inside its own shadow DOM and has no default slot, so cells written as its children are never shown. Every pattern below shows the `<mds-calendar>` markup that puts the cells in each state.\n\n#### Basic Cell Inside a Calendar\n\nThe typical form - let the parent render the cells and drive all their attributes (`date` in ISO `YYYY-MM-DD` format, `label`, `month`, `selection`, ...).\n\n```html\n<mds-calendar start-date=\"2024-06-01\" end-date=\"2024-06-15\"></mds-calendar>\n```\n\n#### Today Marker\n\nThe parent sets the `today` boolean attribute on the cell that matches the current date, which applies the accent-tinted styling that distinguishes today from other days. Set `hide-today` on the calendar to drop it.\n\n```html\n<mds-calendar></mds-calendar>\n<mds-calendar hide-today></mds-calendar>\n```\n\n#### Selection Range - Start, Middle, and End Positions\n\nThe parent sets `selection` to express where a cell falls inside the active range. The `start` and `end` values add rounded caps; `middle` fills the span between them; `single` applies both caps for a one-day selection.\n\n```html\n<!-- 3 June: start, 4 June: middle, 5 June: end -->\n<mds-calendar start-date=\"2024-06-03\" end-date=\"2024-06-05\"></mds-calendar>\n```\n\n#### Single-Day Selection\n\nThe parent uses `selection=\"single\"` for the day of a single picker, for a range whose two ends are the same day, and for the start of a range still waiting for its end. This applies a fully rounded pill on both sides rather than an open-ended bar.\n\n```html\n<mds-calendar single-picker start-date=\"2024-06-10\"></mds-calendar>\n```\n\n#### Preview (Hover) Selection\n\nWhile the user hovers toward the second boundary of a range, the parent sets `preview` on the cells between the start and the hovered day. The cells render distinct preview styling until the selection is committed.\n\n```html\n<!-- range mode with a start and no end: hovering a later day previews the range -->\n<mds-calendar start-date=\"2024-06-07\"></mds-calendar>\n```\n\n#### Days from Adjacent Months\n\nThe parent renders the leading and trailing days that fill the grid but belong to the previous or next month with `month=\"other\"`. Inside `<mds-calendar>` these cells are dimmed and visible; set `--mds-calendar-cell-other-month-visibility: hidden` on the calendar to hide them.\n\n```html\n<mds-calendar view-date=\"2024-06-01\" style=\"--mds-calendar-cell-other-month-visibility: hidden;\"></mds-calendar>\n```\n\n#### Disabled Day\n\nThe parent sets the `disabled` boolean attribute on days that cannot be selected - the dates outside its `min`/`max` range. A disabled cell removes pointer events and applies the disabled color automatically.\n\n```html\n<mds-calendar view-date=\"2024-06-01\" min=\"2024-06-10\"></mds-calendar>\n```\n\n#### Styling Customization\n\nThe cells live in the calendar's shadow DOM, so their public `--mds-calendar-cell-*` CSS custom properties reach them by inheritance: set them on the `<mds-calendar>` host (or on a parent selector), next to the public custom properties the calendar documents for them. The colors of the weekend, selected, preselected, disabled and adjacent-month days are not public: they follow the theme. Use the semantic color roles so dark mode, named themes and high contrast keep working.\n\n```css\n.booking-calendar mds-calendar {\n --mds-calendar-cell-other-month-visibility: hidden;\n --mds-calendar-cell-background: rgb(var(--magma-wash-soft));\n --mds-calendar-cell-color: rgb(var(--magma-text-muted));\n}\n```\n",
6913
+ "1. Description": "The `<mds-calendar-cell>` web component represents a single selectable day inside the [`<mds-calendar>`](../mds-calendar/AGENTS.md) grid. It is a presentational child that renders the day number and exposes attributes the parent calendar drives to express the day's role and its position within a selection range.\n\n#### Semantic Behavior\n\n- **Compound child only**: It is rendered only by `<mds-calendar>`, which generates one cell per day of the visible month grid inside its own shadow DOM (the calendar has no default slot): consumers never write it, neither standalone nor as a child of the calendar.\n- **Parent-driven selection**: The cell holds no internal selection state. The parent calendar drives the `date`, `selection` and `preview` attributes to paint range boundaries and intermediate days; the cell only reflects what it is given.\n- **No own events**: Clicks and hover are handled by the parent (range building, preview, and the `mdsCalendarChange` / `mdsCalendarPreselect` events from `<mds-calendar>`). The cell itself emits nothing.\n- **Disabled state**: When `disabled` is set the day cannot be activated; the parent applies this for days outside the calendar's `min`/`max` range.\n- **Today marker**: `today` is a presentational flag the parent sets on the cell matching the current date, used only for styling emphasis.\n\n#### Properties & Visual Configurations\n\nMost props are state mirrors written by the parent rather than knobs a consumer tunes directly.\n\n- **`month`**: Distinguishes how the day relates to the displayed month - `current` for in-month days, `other` for leading/trailing days spilling in from adjacent months. The type also allows `weekend`, which is deprecated: the calendar never sets it and it has no styling of its own, since the weekend color comes from the cell's position (the last two columns of the week).\n- **`selection`**: Marks the cell's position within an active range - `start`, `end`, `middle`, or `single` (a day alone: a one-day range, the start of a range waiting for its end, the day of a single picker); absence or `none` means unselected. A chosen `start`, `end` or `single` is a full dot, the same mark for both ends; `middle` and the halves of the ends that reach it are the band of the range.\n- **`preview`**: When `true`, the selection is a preview of the day under the pointer rather than a chosen one: a paler band, and the `end` (or a `single`) drawn as a ring, not chosen yet. The `start` of a preview is the day already chosen and keeps its full dot.\n- **`orientation`**: Selection-connector direction. The type allows `horizontal`, `vertical`, and `both`, but only `horizontal` is currently supported.\n- **`date`**: The cell's ISO `YYYY-MM-DD` date; the parent matches against it to compute selection state, so it is required for the cell to participate in range logic.\n",
6914
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-calendar-cell>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n`<mds-calendar-cell>` is an internal subpart: its real parent [`<mds-calendar>`](../mds-calendar/AGENTS.md) renders one cell per day inside its own shadow DOM and has no default slot, so cells written as its children are never shown. Every pattern below shows the `<mds-calendar>` markup that puts the cells in each state.\n\n#### Basic Cell Inside a Calendar\n\nThe typical form - let the parent render the cells and drive all their attributes (`date` in ISO `YYYY-MM-DD` format, `label`, `month`, `selection`, ...).\n\n```html\n<mds-calendar start-date=\"2024-06-01\" end-date=\"2024-06-15\"></mds-calendar>\n```\n\n#### Today Marker\n\nThe parent sets the `today` boolean attribute on the cell that matches the current date, which applies the accent-tinted styling that distinguishes today from other days. Set `hide-today` on the calendar to drop it.\n\n```html\n<mds-calendar></mds-calendar>\n<mds-calendar hide-today></mds-calendar>\n```\n\n#### Selection Range - Start, Middle, and End Positions\n\nThe parent sets `selection` to express where a cell falls inside the active range. The `start` and `end` values are full dots, the same mark, with the band rounded around them; `middle` fills the span between them; `single` is a full dot with no band.\n\n```html\n<!-- 3 June: start, 4 June: middle, 5 June: end -->\n<mds-calendar start-date=\"2024-06-03\" end-date=\"2024-06-05\"></mds-calendar>\n```\n\n#### Single-Day Selection\n\nThe parent uses `selection=\"single\"` for the day of a single picker, for a range whose two ends are the same day, and for the start of a range still waiting for its end. The day is a full dot, with no band, as it reaches no other day.\n\n```html\n<mds-calendar single-picker start-date=\"2024-06-10\"></mds-calendar>\n```\n\n#### Preview (Hover) Selection\n\nWhile the user hovers toward the end of a range, the parent sets `preview` on the cells from the start to the hovered day: the band is paler, the hovered day is a ring, and the start keeps the full dot of a chosen day. A hovered day that a click would make the new start, one before the start, is a `single` `preview` alone: a ring with no band.\n\n```html\n<!-- range mode with a start and no end: hovering a later day previews the range -->\n<mds-calendar start-date=\"2024-06-07\"></mds-calendar>\n```\n\n#### Days from Adjacent Months\n\nThe parent renders the leading and trailing days that fill the grid but belong to the previous or next month with `month=\"other\"`. Inside `<mds-calendar>` these cells are dimmed and visible; set `--mds-calendar-cell-other-month-visibility: hidden` on the calendar to hide them.\n\n```html\n<mds-calendar view-date=\"2024-06-01\" style=\"--mds-calendar-cell-other-month-visibility: hidden;\"></mds-calendar>\n```\n\n#### Disabled Day\n\nThe parent sets the `disabled` boolean attribute on days that cannot be selected - the dates outside its `min`/`max` range. A disabled cell removes pointer events and applies the disabled color automatically.\n\n```html\n<mds-calendar view-date=\"2024-06-01\" min=\"2024-06-10\"></mds-calendar>\n```\n\n#### Styling Customization\n\nThe cells live in the calendar's shadow DOM, so their public `--mds-calendar-cell-*` CSS custom properties reach them by inheritance: set them on the `<mds-calendar>` host (or on a parent selector), next to the public custom properties the calendar documents for them. The colors of the weekend, selected, preselected, disabled and adjacent-month days are not public: they follow the theme. Use the semantic color roles so dark mode, named themes and high contrast keep working.\n\n```css\n.booking-calendar mds-calendar {\n --mds-calendar-cell-other-month-visibility: hidden;\n --mds-calendar-cell-background: rgb(var(--magma-wash-soft));\n --mds-calendar-cell-color: rgb(var(--magma-text-muted));\n}\n```\n",
6545
6915
  "3. Mistakes": "Common incorrect uses of `<mds-calendar-cell>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use the Cell Outside Its Parent Calendar\n\n`<mds-calendar-cell>` is rendered by [`<mds-calendar>`](../mds-calendar/AGENTS.md) itself, one per day inside its shadow DOM. Used in isolation it loses the gap context that drives range connector geometry and no parent coordinates selection across cells; slotted into `<mds-calendar>`, which has no default slot, it is never shown. Let the calendar generate the cells.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar-cell date=\"2024-06-10\" label=\"10\" month=\"current\" selection=\"single\"></mds-calendar-cell>\n\n<!-- CORRECT -->\n<mds-calendar single-picker start-date=\"2024-06-10\"></mds-calendar>\n```\n\n#### Do Not Manage Selection State Locally in the Cell\n\nThe cell is purely presentational - it holds no internal state. Setting `selection` directly on isolated cells and keeping them in sync by hand duplicates the logic the parent calendar already owns and will diverge on re-renders.\n\n```html\n<!-- INCORRECT: manually wiring selection outside mds-calendar -->\n<div class=\"custom-grid\">\n <mds-calendar-cell date=\"2024-06-03\" label=\"3\" selection=\"start\"></mds-calendar-cell>\n <mds-calendar-cell date=\"2024-06-04\" label=\"4\" selection=\"middle\"></mds-calendar-cell>\n <mds-calendar-cell date=\"2024-06-05\" label=\"5\" selection=\"end\"></mds-calendar-cell>\n</div>\n\n<!-- CORRECT: let mds-calendar own range state and drive cell props -->\n<mds-calendar start-date=\"2024-06-03\" end-date=\"2024-06-05\"></mds-calendar>\n```\n\n#### Do Not Pierce the Shadow DOM to Style Internals\n\nThe cells live in the shadow DOM of `<mds-calendar>`: from outside they are adjusted only through their public `--mds-calendar-cell-*` custom properties, set on the calendar, which the cells inherit. Targeting the internal `.action`, `.inner-dot`, or `.area-background` elements via `>>>` or undocumented class selectors couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-calendar-cell >>> .area-background {\n background: hotpink;\n}\nmds-calendar-cell >>> .inner-dot {\n display: none;\n}\n\n/* CORRECT */\nmds-calendar {\n --mds-calendar-cell-other-month-visibility: hidden;\n --mds-calendar-cell-background: rgb(var(--magma-wash-soft));\n}\n```\n"
6546
6916
  },
6547
6917
  "props": [
@@ -6919,49 +7289,61 @@
6919
7289
  {
6920
7290
  "name": "--mds-calendar-cell-preselection-current-month-background",
6921
7291
  "annotation": "prop",
6922
- "docs": "Background for preselected days (current month).",
7292
+ "docs": "Background of the band of a preview, from the start to the day under the pointer (current month).",
6923
7293
  "visibility": "internal"
6924
7294
  },
6925
7295
  {
6926
7296
  "name": "--mds-calendar-cell-preselection-current-month-boundaries-background",
6927
7297
  "annotation": "prop",
6928
- "docs": "Boundary background for preselected days (current month).",
7298
+ "docs": "Fill of the ring of the day under the pointer (current month).",
7299
+ "visibility": "internal"
7300
+ },
7301
+ {
7302
+ "name": "--mds-calendar-cell-preselection-current-month-boundaries-border-color",
7303
+ "annotation": "prop",
7304
+ "docs": "Ring of the day under the pointer, not chosen yet (current month).",
6929
7305
  "visibility": "internal"
6930
7306
  },
6931
7307
  {
6932
7308
  "name": "--mds-calendar-cell-preselection-current-month-boundaries-color",
6933
7309
  "annotation": "prop",
6934
- "docs": "Boundary color for preselected days (current month).",
7310
+ "docs": "Text color of the day under the pointer, the end a click there would pick (current month).",
6935
7311
  "visibility": "internal"
6936
7312
  },
6937
7313
  {
6938
7314
  "name": "--mds-calendar-cell-preselection-current-month-color",
6939
7315
  "annotation": "prop",
6940
- "docs": "Text color for preselected days (current month).",
7316
+ "docs": "Text color of the band of a preview (current month).",
6941
7317
  "visibility": "internal"
6942
7318
  },
6943
7319
  {
6944
7320
  "name": "--mds-calendar-cell-preselection-other-month-background",
6945
7321
  "annotation": "prop",
6946
- "docs": "Background for preselected days (other months).",
7322
+ "docs": "Background of the band of a preview (other months).",
6947
7323
  "visibility": "internal"
6948
7324
  },
6949
7325
  {
6950
7326
  "name": "--mds-calendar-cell-preselection-other-month-boundaries-background",
6951
7327
  "annotation": "prop",
6952
- "docs": "Boundary background for preselected days (other months).",
7328
+ "docs": "Fill of the ring of the day under the pointer (other months).",
7329
+ "visibility": "internal"
7330
+ },
7331
+ {
7332
+ "name": "--mds-calendar-cell-preselection-other-month-boundaries-border-color",
7333
+ "annotation": "prop",
7334
+ "docs": "Ring of the day under the pointer, not chosen yet (other months).",
6953
7335
  "visibility": "internal"
6954
7336
  },
6955
7337
  {
6956
7338
  "name": "--mds-calendar-cell-preselection-other-month-boundaries-color",
6957
7339
  "annotation": "prop",
6958
- "docs": "Boundary color for preselected days (other months).",
7340
+ "docs": "Text color of the day under the pointer (other months).",
6959
7341
  "visibility": "internal"
6960
7342
  },
6961
7343
  {
6962
7344
  "name": "--mds-calendar-cell-preselection-other-month-color",
6963
7345
  "annotation": "prop",
6964
- "docs": "Text color for preselected days (other months).",
7346
+ "docs": "Text color of the band of a preview (other months).",
6965
7347
  "visibility": "internal"
6966
7348
  },
6967
7349
  {
@@ -6985,73 +7367,73 @@
6985
7367
  {
6986
7368
  "name": "--mds-calendar-cell-selection-current-month-background",
6987
7369
  "annotation": "prop",
6988
- "docs": "Background for selected days (current month).",
7370
+ "docs": "Background of the band of a range, between and behind its ends (current month).",
6989
7371
  "visibility": "internal"
6990
7372
  },
6991
7373
  {
6992
7374
  "name": "--mds-calendar-cell-selection-current-month-boundaries-background",
6993
7375
  "annotation": "prop",
6994
- "docs": "Boundary background for selected days (current month).",
7376
+ "docs": "Fill of the dot of a chosen day: either end of a range, or the day of a single picker (current month).",
6995
7377
  "visibility": "internal"
6996
7378
  },
6997
7379
  {
6998
7380
  "name": "--mds-calendar-cell-selection-current-month-boundaries-color",
6999
7381
  "annotation": "prop",
7000
- "docs": "Boundary color for selected days (current month).",
7382
+ "docs": "Text color of the dot of a chosen day (current month).",
7001
7383
  "visibility": "internal"
7002
7384
  },
7003
7385
  {
7004
7386
  "name": "--mds-calendar-cell-selection-current-month-color",
7005
7387
  "annotation": "prop",
7006
- "docs": "Text color for selected days (current month).",
7388
+ "docs": "Text color of the band of a range (current month).",
7007
7389
  "visibility": "internal"
7008
7390
  },
7009
7391
  {
7010
7392
  "name": "--mds-calendar-cell-selection-current-month-weekend-background",
7011
7393
  "annotation": "prop",
7012
- "docs": "Background for selected weekend days (current month).",
7394
+ "docs": "Background of the band of a range on weekend days (current month).",
7013
7395
  "visibility": "internal"
7014
7396
  },
7015
7397
  {
7016
7398
  "name": "--mds-calendar-cell-selection-current-month-weekend-boundaries-background",
7017
7399
  "annotation": "prop",
7018
- "docs": "Boundary background for selected weekend days.",
7400
+ "docs": "Background of the band behind an end of a range on a weekend day.",
7019
7401
  "visibility": "internal"
7020
7402
  },
7021
7403
  {
7022
7404
  "name": "--mds-calendar-cell-selection-current-month-weekend-boundaries-color",
7023
7405
  "annotation": "prop",
7024
- "docs": "Boundary color for selected weekend days.",
7406
+ "docs": "Text color of the dot of an end of a range on a weekend day.",
7025
7407
  "visibility": "internal"
7026
7408
  },
7027
7409
  {
7028
7410
  "name": "--mds-calendar-cell-selection-current-month-weekend-color",
7029
7411
  "annotation": "prop",
7030
- "docs": "Text color for selected weekend days (current month).",
7412
+ "docs": "Text color of the band of a range on weekend days (current month).",
7031
7413
  "visibility": "internal"
7032
7414
  },
7033
7415
  {
7034
7416
  "name": "--mds-calendar-cell-selection-other-month-background",
7035
7417
  "annotation": "prop",
7036
- "docs": "Background for selected days (other months).",
7418
+ "docs": "Background of the band of a range (other months).",
7037
7419
  "visibility": "internal"
7038
7420
  },
7039
7421
  {
7040
7422
  "name": "--mds-calendar-cell-selection-other-month-boundaries-background",
7041
7423
  "annotation": "prop",
7042
- "docs": "Boundary background for selected days (other months).",
7424
+ "docs": "Fill of the dot of a chosen day (other months).",
7043
7425
  "visibility": "internal"
7044
7426
  },
7045
7427
  {
7046
7428
  "name": "--mds-calendar-cell-selection-other-month-boundaries-color",
7047
7429
  "annotation": "prop",
7048
- "docs": "Boundary color for selected days (other months).",
7430
+ "docs": "Text color of the dot of a chosen day (other months).",
7049
7431
  "visibility": "internal"
7050
7432
  },
7051
7433
  {
7052
7434
  "name": "--mds-calendar-cell-selection-other-month-color",
7053
7435
  "annotation": "prop",
7054
- "docs": "Text color for selected days (other months).",
7436
+ "docs": "Text color of the band of a range (other months).",
7055
7437
  "visibility": "internal"
7056
7438
  },
7057
7439
  {
@@ -7093,8 +7475,8 @@
7093
7475
  "mds-button"
7094
7476
  ],
7095
7477
  "mds-button": [
7096
- "mds-spinner",
7097
7478
  "mds-icon",
7479
+ "mds-spinner",
7098
7480
  "mds-text"
7099
7481
  ],
7100
7482
  "mds-calendar": [
@@ -7136,9 +7518,9 @@
7136
7518
  }
7137
7519
  ],
7138
7520
  "usage": {
7139
- "1. Description": "The `<mds-card>` web component is the surface container of the Magma Design System: a styled, self-contained panel that groups related media, heading, body and action content into a single bounded region. It is a pure layout shell built on named slots and compound children rather than a replacement for any single HTML primitive.\n\n#### Semantic Behavior\n\n- **Layout is inferred, not declared**: The card detects which of the `media` / `header` / `content` / `footer` regions are present, again whenever its content changes, and reshapes itself to whatever content you provide.\n- **Compound parent/child relationship**: `<mds-card-media>`, `<mds-card-header>`, `<mds-card-content>` and `<mds-card-footer>` are recognized by tag name and mapped onto the corresponding region, so they slot in without an explicit `slot` attribute. Plain elements given the matching `slot` value land in that region and take part in the managed grid the same way.\n- **Responsive by width**: The card's internal layout switches between stacked and media-beside-content arrangements based on the card's own width, independent of viewport or theme.\n- **One inset, shared by the regions**: The card pads its regions once, with `--magma-rhythm-inset` (600), and sets them `--magma-rhythm-title-content` (300) apart, so the title of a card stands nearer to its content than to the edge. The regions pad nothing of their own (`rhythm/inset`, `rhythm/shared-inset` in the design language).\n- **The media reaches the edges it touches**: `<mds-card-media>` leaves the inset on the sides where it meets the edge of the card: both sides when the regions are stacked, the top too when no header stands above it, the top, the bottom and the start when it stands beside the content. From the other regions it stands 300, as they do from each other (`rhythm/media-bleed`).\n- **The actions stand apart**: The footer stands `--magma-rhythm-content-actions` (600) from the region before it, as the row of actions of a form or of a dialog: the actions act on the whole card, not on its last line (`rhythm/content-actions`).\n- **The footer closes the card**: The footer region sits at the bottom of the card whatever the other regions are. When the card is taller than its parts (a media taller than header and footer together, or a grid row that stretches a set of cards to one height) and there is no content to take the free space, that space stays above the footer, in the card's background.\n- **Slot regions are fixed**: Only the four named regions are rendered; there is no default (unnamed) slot, so loose text or elements without a recognized slot/tag are not laid out.\n\n#### Properties & Visual Configurations\n\n`<mds-card>` does not use the shared `variant` / `tone` ladders defined in [`agents/variants.md`](../../../../agents/variants.md); it exposes a single behavioral prop.\n\n- **`disableAutoGrid`** (default `false`) toggles the intrinsic responsive grid. Leave it off to let the card own the placement and reflow of its regions; set it to opt out of the managed grid and lay the slotted content out yourself.\n\nThe inset and the gap follow the rhythm roles, so a density theme moves them with every other space. `--mds-card-padding` and `--mds-card-gap` override them for a set of cards, with another rhythm role, never a step; the background of the card and of its regions is `--mds-card-background`.\n",
7140
- "2. Examples": "Correct and idiomatic ways to use the `<mds-card>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Full Card with All Four Regions\n\nThe most common form. Use `<mds-card-header>`, `<mds-card-media>`, `<mds-card-content>`, and `<mds-card-footer>` as direct children. Each compound child self-assigns to its slot - no explicit `slot` attribute needed.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo della scheda</mds-text>\n </mds-card-header>\n <mds-card-media>\n <mds-img src=\"/immagini/copertina.jpg\" alt=\"Copertina del contenuto della scheda\" class=\"object-cover\"></mds-img>\n </mds-card-media>\n <mds-card-content>\n <mds-text>\n Descrizione dettagliata del contenuto della scheda.\n </mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Annulla\"></mds-button>\n <mds-button variant=\"primary\" tone=\"strong\" label=\"Conferma\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Header + Content (No Media)\n\nOmit the regions you do not need - the card detects which regions are present and adapts its grid layout accordingly. A header-and-content-only card stays single-column.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Riepilogo ordine</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>\n Il tuo ordine e' stato elaborato correttamente.\n </mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Media + Content + Footer (No Header)\n\nOmitting the header region shifts media to the top and content immediately below. Useful for image-led catalog cards.\n\n```html\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/immagini/prodotto.jpg\" alt=\"Il prodotto della gamma autunnale\" class=\"object-cover\"></mds-img>\n </mds-card-media>\n <mds-card-content>\n <mds-text>Descrizione prodotto disponibile nella gamma autunnale.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button variant=\"primary\" label=\"Aggiungi al carrello\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Header with Action Button via `mds-card-header`\n\n`<mds-card-header>` has a dedicated `action` slot for icon buttons placed in the trailing position. Use it instead of laying out the button manually.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Profilo utente</mds-text>\n <mds-button\n slot=\"action\"\n icon=\"mi/round/more-vert\"\n aria-label=\"Altre azioni\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Mario Rossi - Amministratore di sistema</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Media with Overlay Content via `mds-card-media`\n\n`<mds-card-media>` exposes a `content` slot that renders in front of the media element. Use it for captions, badges, or status chips overlaid on an image.\n\n```html\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/immagini/evento.jpg\" alt=\"Il palco della conferenza annuale\" class=\"object-cover\"></mds-img>\n <mds-badge slot=\"content\" variant=\"info\" tone=\"strong\">In corso</mds-badge>\n </mds-card-media>\n <mds-card-content>\n <mds-text typography=\"h6\">Conferenza annuale 2025</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Using Raw Slot Attributes Instead of Compound Children\n\nWhen the compound children (`mds-card-*`) do not fit the use case, assign the `slot` attribute directly on any element, with the same four values: `media`, `header`, `content`, and `footer`. The card reads the regions from the `slot` values, so plain elements get the same managed grid and the same inset as the compound children: do not pad them.\n\n```html\n<mds-card>\n <div slot=\"header\" class=\"flex items-center gap-inline\">\n <mds-avatar initials=\"LB\"></mds-avatar>\n <mds-text typography=\"h6\">Luca Bianchi</mds-text>\n </div>\n <mds-img slot=\"media\" src=\"/immagini/lavoro.jpg\" alt=\"Luca Bianchi in cantiere\" class=\"object-cover\"></mds-img>\n <mds-text slot=\"content\">\n Responsabile del progetto infrastrutture.\n </mds-text>\n</mds-card>\n```\n\n#### Disabling the Auto-Grid\n\nSet `disable-auto-grid` to opt out of the managed responsive grid. The regions stack in slot order (media, header, content, footer), whatever their order in the markup, and you own all layout decisions.\n\n```html\n<mds-card disable-auto-grid>\n <mds-card-header>\n <mds-text typography=\"h6\">Layout personalizzato</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Il contenuto e' disposto senza griglia automatica.</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nThe card already takes its inset and its gap from the rhythm roles (`--magma-rhythm-inset`, `--magma-rhythm-title-content`), and a density theme moves them. Set `--mds-card-gap` and `--mds-card-padding` on the host or a parent selector only to give a set of cards another relation of the rhythm, written as its role, never as a step. `--mds-card-background` recolors the card and its regions together; name a surface role so dark mode keeps working.\n\n```css\n.scheda-dati mds-card {\n --mds-card-gap: var(--magma-rhythm-between-fields);\n --mds-card-background: rgb(var(--magma-surface-overlay));\n}\n```\n\n#### Customizing the Layout Part\n\nThe inner grid element is exposed as `::part(layout)`. Use it only for layout-level overrides that the CSS custom properties cannot cover, such as overriding the `border-radius` of the inner container.\n\n```css\n.scheda-highlight mds-card::part(layout) {\n border-radius: var(--magma-radius-xl);\n}\n```\n",
7141
- "3. Mistakes": "Common incorrect uses of `<mds-card>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Put Content Outside the Four Named Slots\n\n`<mds-card>` has no default (unnamed) slot. Loose text or elements placed without a recognized `slot` attribute - or without using an `mds-card-*` compound child - are silently ignored and never rendered.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <p>Questo testo non verra' mai visualizzato.</p>\n <mds-button label=\"Azione\"></mds-button>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-content>\n <mds-text>Questo testo e' correttamente posizionato nel content slot.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button label=\"Azione\" variant=\"primary\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Do Not Use `mds-card-*` Children Outside `<mds-card>`\n\nCompound children (`mds-card-header`, `mds-card-media`, `mds-card-content`, `mds-card-footer`) rely on `<mds-card>` for layout context. Used standalone they render without the managed grid and without the card's visual chrome.\n\n```html\n<!-- INCORRECT -->\n<div class=\"mia-sezione\">\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo standalone</mds-text>\n </mds-card-header>\n</div>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo nella scheda</mds-text>\n </mds-card-header>\n</mds-card>\n```\n\n#### Do Not Pierce the Shadow DOM with Undocumented Selectors\n\nThe only supported customization surface is `--mds-card-background`, `--mds-card-gap`, `--mds-card-padding`, and `::part(layout)`. Targeting internal class names with `>>>`, `/deep/`, or any selector that reaches inside the shadow root couples your code to implementation details and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-card >>> .layout {\n padding: 16px;\n}\nmds-card .layout--cfhm {\n grid-template-columns: 1fr 1fr;\n}\n\n/* CORRECT */\nmds-card {\n --mds-card-padding: calc(var(--spacing) * 400);\n}\nmds-card::part(layout) {\n border-radius: var(--magma-radius-xl);\n}\n```\n\n#### Do Not Assign an Explicit `slot` Attribute to `mds-card-*` Children\n\n`mds-card-header`, `mds-card-media`, `mds-card-content`, and `mds-card-footer` already set their own `slot` attribute on the host element from inside the component. Adding it again from the outside is redundant and may conflict with internal wiring.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-header slot=\"header\">...</mds-card-header>\n <mds-card-content slot=\"content\">...</mds-card-content>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-header>...</mds-card-header>\n <mds-card-content>...</mds-card-content>\n</mds-card>\n```\n\n#### Do Not Put Media Elements Directly in the `header` Slot\n\nThe `header` slot is intended for title and action controls. Placing an `<mds-img>` or `<img>` directly there bypasses the media region's responsive two-column behavior. Use the `media` slot (or `<mds-card-media>`) for images and videos.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-img src=\"/immagini/banner.jpg\" alt=\"Banner della campagna\"></mds-img>\n </mds-card-header>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/immagini/banner.jpg\" alt=\"Banner della campagna\" class=\"object-cover\"></mds-img>\n </mds-card-media>\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo della scheda</mds-text>\n </mds-card-header>\n</mds-card>\n```\n\n#### Do Not Pad the Regions of a Card\n\nThe card pads its regions once, with its inset. A padding on a region, or on a plain element in a slot, adds to the inset: the title moves away from the edge and from its content, as when every region padded `p-400` of its own and the title stood 800 from its text. A padding on the media also takes it away from the edges it should reach.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-header class=\"p-400\">\n <mds-text typography=\"h6\">Riepilogo ordine</mds-text>\n </mds-card-header>\n <mds-text slot=\"content\" class=\"px-400\">Il tuo ordine e' stato elaborato correttamente.</mds-text>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Riepilogo ordine</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Il tuo ordine e' stato elaborato correttamente.</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Do Not Override Card Dimensions with Inline Styles\n\n`<mds-card>` manages its own min-height and responsive grid. A fixed `height` clips the regions (the card hides its overflow), and a fixed `width` pins the container-query layout instead of letting it follow the space its container gives.\n\n```html\n<!-- INCORRECT -->\n<mds-card style=\"width: 300px; height: 200px;\">\n ...\n</mds-card>\n\n<!-- CORRECT: size the card from a parent container or CSS custom properties -->\n<div class=\"w-[300px]\">\n <mds-card>\n ...\n </mds-card>\n</div>\n```\n"
7521
+ "1. Description": "The `<mds-card>` web component is the surface container of the Magma Design System: a styled, self-contained panel that groups related media, heading, body and action content into a single bounded region. It is a pure layout shell built on named slots and compound children rather than a replacement for any single HTML primitive.\n\n#### Semantic Behavior\n\n- **Layout is inferred, not declared**: The card detects which of the `media` / `header` / `content` / `footer` regions are present, again whenever its content changes, and reshapes itself to whatever content you provide.\n- **Compound parent/child relationship**: `<mds-card-media>`, `<mds-card-header>`, `<mds-card-content>` and `<mds-card-footer>` are recognized by tag name and mapped onto the corresponding region, so they slot in without an explicit `slot` attribute. Plain elements given the matching `slot` value land in that region and take part in the managed grid the same way.\n- **Responsive by width**: The card's internal layout switches between stacked and media-beside-content arrangements based on the card's own width, independent of viewport or theme.\n- **One inset, shared by the regions**: The card pads its regions once, with `--magma-rhythm-inset` (600), and sets them `--magma-rhythm-title-content` (300) apart, so the title of a card stands nearer to its content than to the edge. The regions pad nothing of their own (`rhythm/inset`, `rhythm/shared-inset` in the design language).\n- **The media reaches the edges it touches**: `<mds-card-media>` leaves the inset on the sides where it meets the edge of the card: both sides when the regions are stacked, the top too when no header stands above it, the top, the bottom and the start when it stands beside the content. From the other regions it stands 300, as they do from each other (`rhythm/media-bleed`).\n- **The actions stand apart**: The footer stands `--magma-rhythm-content-actions` (600) from the region before it, as the row of actions of a form or of a dialog: the actions act on the whole card, not on its last line (`rhythm/content-actions`).\n- **The footer closes the card**: The footer region sits at the bottom of the card whatever the other regions are. When the card is taller than its parts (a media taller than header and footer together, or a grid row that stretches a set of cards to one height) and there is no content to take the free space, that space stays above the footer, in the card's background.\n- **The card sets the text of its own surface**: It paints `surface-raised` and sets its `color` to `text-default`, the pair the contrast gate measures, so its regions inherit the text of the card, not the colour of what the card stands on: on a band of colour (`surfaces/intro-band`) its text keeps reading without a reset. A `text-*` class or a `color` on the host still wins.\n- **Slot regions are fixed**: Only the four named regions are rendered; there is no default (unnamed) slot, so loose text or elements without a recognized slot/tag are not laid out.\n\n#### Properties & Visual Configurations\n\n`<mds-card>` does not use the shared `variant` / `tone` ladders defined in [`agents/variants.md`](../../../../agents/variants.md); it exposes a single behavioral prop.\n\n- **`disableAutoGrid`** (default `false`) toggles the intrinsic responsive grid. Leave it off to let the card own the placement and reflow of its regions; set it to opt out of the managed grid and lay the slotted content out yourself.\n\nThe inset and the gap follow the rhythm roles, so a density theme moves them with every other space. `--mds-card-padding` and `--mds-card-gap` override them for a set of cards, with another rhythm role, never a step; the background of the card and of its regions is `--mds-card-background`, its text `--mds-card-color`: set them together, so the text keeps reading on the surface.\n",
7522
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-card>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Full Card with All Four Regions\n\nThe most common form. Use `<mds-card-header>`, `<mds-card-media>`, `<mds-card-content>`, and `<mds-card-footer>` as direct children. Each compound child self-assigns to its slot - no explicit `slot` attribute needed.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo della scheda</mds-text>\n </mds-card-header>\n <mds-card-media>\n <mds-img src=\"/immagini/copertina.jpg\" alt=\"Copertina del contenuto della scheda\" class=\"object-cover\"></mds-img>\n </mds-card-media>\n <mds-card-content>\n <mds-text>\n Descrizione dettagliata del contenuto della scheda.\n </mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Annulla\"></mds-button>\n <mds-button variant=\"primary\" tone=\"strong\" label=\"Conferma\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Header + Content (No Media)\n\nOmit the regions you do not need - the card detects which regions are present and adapts its grid layout accordingly. A header-and-content-only card stays single-column.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Riepilogo ordine</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>\n Il tuo ordine e' stato elaborato correttamente.\n </mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Media + Content + Footer (No Header)\n\nOmitting the header region shifts media to the top and content immediately below. Useful for image-led catalog cards.\n\n```html\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/immagini/prodotto.jpg\" alt=\"Il prodotto della gamma autunnale\" class=\"object-cover\"></mds-img>\n </mds-card-media>\n <mds-card-content>\n <mds-text>Descrizione prodotto disponibile nella gamma autunnale.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button variant=\"primary\" label=\"Aggiungi al carrello\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Header with Action Button via `mds-card-header`\n\n`<mds-card-header>` has a dedicated `action` slot for icon buttons placed in the trailing position. Use it instead of laying out the button manually.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Profilo utente</mds-text>\n <mds-button\n slot=\"action\"\n icon=\"mi/round/more-vert\"\n aria-label=\"Altre azioni\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Mario Rossi - Amministratore di sistema</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Media with Overlay Content via `mds-card-media`\n\n`<mds-card-media>` exposes a `content` slot that renders in front of the media element. Use it for captions, badges, or status chips overlaid on an image.\n\n```html\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/immagini/evento.jpg\" alt=\"Il palco della conferenza annuale\" class=\"object-cover\"></mds-img>\n <mds-badge slot=\"content\" variant=\"info\" tone=\"strong\">In corso</mds-badge>\n </mds-card-media>\n <mds-card-content>\n <mds-text typography=\"h6\">Conferenza annuale 2025</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Using Raw Slot Attributes Instead of Compound Children\n\nWhen the compound children (`mds-card-*`) do not fit the use case, assign the `slot` attribute directly on any element, with the same four values: `media`, `header`, `content`, and `footer`. The card reads the regions from the `slot` values, so plain elements get the same managed grid and the same inset as the compound children: do not pad them.\n\n```html\n<mds-card>\n <div slot=\"header\" class=\"flex items-center gap-inline\">\n <mds-avatar initials=\"LB\"></mds-avatar>\n <mds-text typography=\"h6\">Luca Bianchi</mds-text>\n </div>\n <mds-img slot=\"media\" src=\"/immagini/lavoro.jpg\" alt=\"Luca Bianchi in cantiere\" class=\"object-cover\"></mds-img>\n <mds-text slot=\"content\">\n Responsabile del progetto infrastrutture.\n </mds-text>\n</mds-card>\n```\n\n#### Disabling the Auto-Grid\n\nSet `disable-auto-grid` to opt out of the managed responsive grid. The regions stack in slot order (media, header, content, footer), whatever their order in the markup, and you own all layout decisions.\n\n```html\n<mds-card disable-auto-grid>\n <mds-card-header>\n <mds-text typography=\"h6\">Layout personalizzato</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Il contenuto e' disposto senza griglia automatica.</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nThe card already takes its inset and its gap from the rhythm roles (`--magma-rhythm-inset`, `--magma-rhythm-title-content`), and a density theme moves them. Set `--mds-card-gap` and `--mds-card-padding` on the host or a parent selector only to give a set of cards another relation of the rhythm, written as its role, never as a step. `--mds-card-background` recolors the card and its regions together, `--mds-card-color` their text (`text-default` by default); name a surface role and the text role that reads on it, so dark mode keeps working.\n\n```css\n.scheda-dati mds-card {\n --mds-card-gap: var(--magma-rhythm-between-fields);\n --mds-card-background: rgb(var(--magma-surface-overlay));\n}\n\n.scheda-invertita mds-card {\n --mds-card-background: rgb(var(--magma-surface-inverse));\n --mds-card-color: rgb(var(--magma-on-inverse));\n}\n```\n\n#### Customizing the Layout Part\n\nThe inner grid element is exposed as `::part(layout)`. Use it only for layout-level overrides that the CSS custom properties cannot cover, such as overriding the `border-radius` of the inner container.\n\n```css\n.scheda-highlight mds-card::part(layout) {\n border-radius: var(--magma-radius-xl);\n}\n```\n",
7523
+ "3. Mistakes": "Common incorrect uses of `<mds-card>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Put Content Outside the Four Named Slots\n\n`<mds-card>` has no default (unnamed) slot. Loose text or elements placed without a recognized `slot` attribute - or without using an `mds-card-*` compound child - are silently ignored and never rendered.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <p>Questo testo non verra' mai visualizzato.</p>\n <mds-button label=\"Azione\"></mds-button>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-content>\n <mds-text>Questo testo e' correttamente posizionato nel content slot.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button label=\"Azione\" variant=\"primary\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Do Not Use `mds-card-*` Children Outside `<mds-card>`\n\nCompound children (`mds-card-header`, `mds-card-media`, `mds-card-content`, `mds-card-footer`) rely on `<mds-card>` for layout context. Used standalone they render without the managed grid and without the card's visual chrome.\n\n```html\n<!-- INCORRECT -->\n<div class=\"mia-sezione\">\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo standalone</mds-text>\n </mds-card-header>\n</div>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo nella scheda</mds-text>\n </mds-card-header>\n</mds-card>\n```\n\n#### Do Not Pierce the Shadow DOM with Undocumented Selectors\n\nThe only supported customization surface is `--mds-card-background`, `--mds-card-color`, `--mds-card-gap`, `--mds-card-padding`, and `::part(layout)`. Targeting internal class names with `>>>`, `/deep/`, or any selector that reaches inside the shadow root couples your code to implementation details and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-card >>> .layout {\n padding: 16px;\n}\nmds-card .layout--cfhm {\n grid-template-columns: 1fr 1fr;\n}\n\n/* CORRECT */\nmds-card {\n --mds-card-padding: calc(var(--spacing) * 400);\n}\nmds-card::part(layout) {\n border-radius: var(--magma-radius-xl);\n}\n```\n\n#### Do Not Assign an Explicit `slot` Attribute to `mds-card-*` Children\n\n`mds-card-header`, `mds-card-media`, `mds-card-content`, and `mds-card-footer` already set their own `slot` attribute on the host element from inside the component. Adding it again from the outside is redundant and may conflict with internal wiring.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-header slot=\"header\">...</mds-card-header>\n <mds-card-content slot=\"content\">...</mds-card-content>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-header>...</mds-card-header>\n <mds-card-content>...</mds-card-content>\n</mds-card>\n```\n\n#### Do Not Put Media Elements Directly in the `header` Slot\n\nThe `header` slot is intended for title and action controls. Placing an `<mds-img>` or `<img>` directly there bypasses the media region's responsive two-column behavior. Use the `media` slot (or `<mds-card-media>`) for images and videos.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-img src=\"/immagini/banner.jpg\" alt=\"Banner della campagna\"></mds-img>\n </mds-card-header>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/immagini/banner.jpg\" alt=\"Banner della campagna\" class=\"object-cover\"></mds-img>\n </mds-card-media>\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo della scheda</mds-text>\n </mds-card-header>\n</mds-card>\n```\n\n#### Do Not Pad the Regions of a Card\n\nThe card pads its regions once, with its inset. A padding on a region, or on a plain element in a slot, adds to the inset: the title moves away from the edge and from its content, as when every region padded `p-400` of its own and the title stood 800 from its text. A padding on the media also takes it away from the edges it should reach.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-header class=\"p-400\">\n <mds-text typography=\"h6\">Riepilogo ordine</mds-text>\n </mds-card-header>\n <mds-text slot=\"content\" class=\"px-400\">Il tuo ordine e' stato elaborato correttamente.</mds-text>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Riepilogo ordine</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Il tuo ordine e' stato elaborato correttamente.</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Do Not Override Card Dimensions with Inline Styles\n\n`<mds-card>` manages its own min-height and responsive grid. A fixed `height` clips the regions (the card hides its overflow), and a fixed `width` pins the container-query layout instead of letting it follow the space its container gives.\n\n```html\n<!-- INCORRECT -->\n<mds-card style=\"width: 300px; height: 200px;\">\n ...\n</mds-card>\n\n<!-- CORRECT: size the card from a parent container or CSS custom properties -->\n<div class=\"w-[300px]\">\n <mds-card>\n ...\n </mds-card>\n</div>\n```\n"
7142
7524
  },
7143
7525
  "props": [
7144
7526
  {
@@ -7181,6 +7563,12 @@
7181
7563
  "docs": "Sets the background color of the card and of its regions (`mds-card-header`, `mds-card-media`, `mds-card-content`, `mds-card-footer`)",
7182
7564
  "visibility": "public"
7183
7565
  },
7566
+ {
7567
+ "name": "--mds-card-color",
7568
+ "annotation": "prop",
7569
+ "docs": "Sets the text color of the card, inherited by its regions, `--magma-text-default` by default: set it together with `--mds-card-background`, so the text keeps reading on the surface",
7570
+ "visibility": "public"
7571
+ },
7184
7572
  {
7185
7573
  "name": "--mds-card-gap",
7186
7574
  "annotation": "prop",
@@ -7280,8 +7668,8 @@
7280
7668
  }
7281
7669
  ],
7282
7670
  "usage": {
7283
- "1. Description": "The `<mds-card-footer>` web component is the footer region of a [`<mds-card>`](../mds-card/AGENTS.md), grouping the trailing content of a card (typically actions such as buttons or supplementary metadata) into the card's bottom region.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-card-footer>` must be a direct slot child of `<mds-card>`; it is not used standalone, nor mixed in as a different child type.\n- **Self-slotting**: Simply placing it inside `<mds-card>` routes it into the parent's footer region without the author setting the slot manually.\n- **Pure layout wrapper**: It has a single default slot and no props, no state, no events, and no ARIA role of its own. It contributes only structural placement, not semantics.\n- **A row of actions**: the actions stand `rhythm/inline` apart at the end of the card; under `--magma-container-actions` of the footer (380px) they stack, each at the full width, in the order of the row, the main action at the bottom (`actions/stacked`).\n- **Presence affects parent layout**: Including or omitting the footer changes how the card arranges its regions.\n\n#### Slot semantics\n\nThis component exposes a single default slot and has no configurable properties. Pass any `text`, `HTML elements`, or other components (commonly `<mds-button>` actions) into the default slot; they will be rendered in the card's footer region. The footer lays its children out in a row aligned to the end, with a fixed gap and padding; the placement of the region and the responsive behavior are owned by the parent `<mds-card>`.\n",
7284
- "2. Examples": "Correct and idiomatic ways to use the `<mds-card-footer>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Action Row Inside a Full Card\n\nThe typical use: a card with header, content, and footer regions, the footer holding the primary and secondary actions. Place `<mds-card-footer>` as a direct child of `<mds-card>` - it routes itself to the footer region automatically.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Riepilogo pratica</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Verifica i dati prima di procedere.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button label=\"Conferma\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Single Call-to-Action\n\nA card with only a media region and a footer is a valid minimal composition. The footer carries a lone action.\n\n```html\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/images/documento.jpg\" alt=\"Anteprima documento\"></mds-img>\n </mds-card-media>\n <mds-card-footer>\n <mds-button label=\"Scarica\" icon=\"mi/baseline/download\" variant=\"primary\" tone=\"weak\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Destructive Action Pattern\n\nUse a `variant=\"error\"` button for destructive operations. Keep the cancel action to the left and the destructive action to the right - the footer's `justify-content: flex-end` naturally aligns both.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Elimina archivio</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Questa operazione non puo essere annullata.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Supplementary Metadata Alongside an Action\n\nThe default slot accepts any slottable content - mix an informational label with a button when status context belongs at the bottom of the card.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Stato richiesta</mds-text>\n </mds-card-header>\n <mds-card-footer>\n <mds-badge label=\"In attesa\" variant=\"warning\" tone=\"weak\"></mds-badge>\n <mds-button label=\"Visualizza dettagli\" variant=\"primary\" tone=\"outline\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Explicit `slot` Attribute on a Plain Element\n\nWhen you prefer a plain `<div>` or need to place a non-`mds-card-*` wrapper in the footer region, set `slot=\"footer\"` explicitly. The element lands in the footer region, but `<mds-card>` infers its managed grid from the tag names of its children: add `disable-auto-grid` to the card, otherwise the regions overlap.\n\n```html\n<mds-card disable-auto-grid>\n <mds-card-header>\n <mds-text typography=\"h6\">Nota operativa</mds-text>\n </mds-card-header>\n <div slot=\"footer\" style=\"display: flex; gap: calc(var(--spacing) * 300);\">\n <mds-button label=\"Chiudi\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button label=\"Salva nota\" variant=\"primary\" tone=\"strong\"></mds-button>\n </div>\n</mds-card>\n```\n",
7671
+ "1. Description": "The `<mds-card-footer>` web component is the footer region of a [`<mds-card>`](../mds-card/AGENTS.md), grouping the trailing content of a card (typically actions such as buttons or supplementary metadata) into the card's bottom region.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-card-footer>` must be a direct slot child of `<mds-card>`; it is not used standalone, nor mixed in as a different child type.\n- **Self-slotting**: Simply placing it inside `<mds-card>` routes it into the parent's footer region without the author setting the slot manually.\n- **Pure layout wrapper**: It has a single default slot and no props, no state, no events, and no ARIA role of its own. It contributes only structural placement, not semantics.\n- **A row of actions**: the actions stand `rhythm/inline` apart at the end of the card; under `--magma-container-actions` of the footer (380px) they stack, each at the full width, in the order of the row, the main action at the bottom (`actions/stacked`). A lone action has no order to keep: it stays at its own width at the end of the row at every width, as an `<mds-button-dropdown>` alone does, so a grid of narrow cards does not repeat a band of buttons.\n- **Presence affects parent layout**: Including or omitting the footer changes how the card arranges its regions.\n\n#### Slot semantics\n\nThis component exposes a single default slot and has no configurable properties. Pass any `text`, `HTML elements`, or other components (commonly `<mds-button>` actions) into the default slot; they will be rendered in the card's footer region. The footer lays its children out in a row aligned to the end, with a fixed gap and padding; the placement of the region and the responsive behavior are owned by the parent `<mds-card>`.\n",
7672
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-card-footer>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Action Row Inside a Full Card\n\nThe typical use: a card with header, content, and footer regions, the footer holding the primary and secondary actions. Place `<mds-card-footer>` as a direct child of `<mds-card>` - it routes itself to the footer region automatically.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Riepilogo pratica</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Verifica i dati prima di procedere.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button label=\"Conferma\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Single Call-to-Action\n\nA card with only a media region and a footer is a valid minimal composition. The footer carries a lone action, which keeps its own width at the end of the row even when the footer is under `--magma-container-actions` (380px): with one action the stack has no order to keep, so it does not stretch it.\n\n```html\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/images/documento.jpg\" alt=\"Anteprima documento\"></mds-img>\n </mds-card-media>\n <mds-card-footer>\n <mds-button label=\"Scarica\" icon=\"mi/baseline/download\" variant=\"primary\" tone=\"weak\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Destructive Action Pattern\n\nUse a `variant=\"error\"` button for destructive operations. Keep the cancel action to the left and the destructive action to the right - the footer's `justify-content: flex-end` naturally aligns both.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Elimina archivio</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Questa operazione non puo essere annullata.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Supplementary Metadata Alongside an Action\n\nThe default slot accepts any slottable content - mix an informational label with a button when status context belongs at the bottom of the card.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Stato richiesta</mds-text>\n </mds-card-header>\n <mds-card-footer>\n <mds-badge label=\"In attesa\" variant=\"warning\" tone=\"weak\"></mds-badge>\n <mds-button label=\"Visualizza dettagli\" variant=\"primary\" tone=\"outline\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Explicit `slot` Attribute on a Plain Element\n\nWhen you prefer a plain `<div>` or need to place a non-`mds-card-*` wrapper in the footer region, set `slot=\"footer\"` explicitly. The element lands in the footer region, but `<mds-card>` infers its managed grid from the tag names of its children: add `disable-auto-grid` to the card, otherwise the regions overlap.\n\n```html\n<mds-card disable-auto-grid>\n <mds-card-header>\n <mds-text typography=\"h6\">Nota operativa</mds-text>\n </mds-card-header>\n <div slot=\"footer\" style=\"display: flex; gap: calc(var(--spacing) * 300);\">\n <mds-button label=\"Chiudi\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button label=\"Salva nota\" variant=\"primary\" tone=\"strong\"></mds-button>\n </div>\n</mds-card>\n```\n",
7285
7673
  "3. Mistakes": "Common incorrect uses of `<mds-card-footer>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-card-footer>` Outside `<mds-card>`\n\n`<mds-card-footer>` self-routes to the `footer` slot of `<mds-card>` via `<Host slot=\"footer\">`. Outside a card it renders as a bare flex row with no visual context and communicates nothing to screen readers.\n\n```html\n<!-- INCORRECT -->\n<mds-card-footer>\n <mds-button label=\"Conferma\" variant=\"primary\"></mds-button>\n</mds-card-footer>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-footer>\n <mds-button label=\"Conferma\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Do Not Assign `slot=\"footer\"` on `<mds-card-footer>` Manually\n\n`<mds-card-footer>` already sets `slot=\"footer\"` on its host via its own render output. Adding it again as an attribute in your markup is redundant: the component writes it itself, overwriting any other value when it renders.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-footer slot=\"footer\">\n <mds-button label=\"Salva\" variant=\"primary\"></mds-button>\n </mds-card-footer>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-footer>\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Do Not Nest `<mds-card-footer>` Inside a Wrapper Element\n\nCompound component children must be direct slot children of the parent - `<mds-card>` has no default slot, so a `<div>` wrapper without a `slot` is not rendered at all, and the `<mds-card-footer>` inside it with it.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <div class=\"azioni\">\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\"></mds-button>\n </mds-card-footer>\n </div>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Do Not Place Multiple `<mds-card-footer>` in One Card\n\n`<mds-card>` maps all children with the footer tag to the same grid area; multiple footers stack or overlap unpredictably. Consolidate all footer content into a single `<mds-card-footer>`.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\"></mds-button>\n </mds-card-footer>\n <mds-card-footer>\n <mds-button label=\"Conferma\" variant=\"primary\"></mds-button>\n </mds-card-footer>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button label=\"Conferma\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Do Not Override Footer Layout via Inline Styles or Undocumented Selectors\n\n`<mds-card-footer>` owns its internal flex layout (the alignment at the end, the actions `--magma-rhythm-inline` apart); its inset is the card's, and the card sets it `--magma-rhythm-content-actions` from the region before it. Overriding it with inline `style` or by targeting shadow internals breaks theme consistency and couples code to implementation details. If the parent card's spacing must change, use `<mds-card>`'s documented `--mds-card-gap` and `--mds-card-padding` custom properties on the card host, with a rhythm role.\n\n```html\n<!-- INCORRECT -->\n<mds-card-footer style=\"justify-content: flex-start; padding: 0;\">\n <mds-button label=\"Salva\" variant=\"primary\"></mds-button>\n</mds-card-footer>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-footer>\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n"
7286
7674
  },
7287
7675
  "props": [],
@@ -7418,9 +7806,9 @@
7418
7806
  }
7419
7807
  ],
7420
7808
  "usage": {
7421
- "1. Description": "The `<mds-chip>` web component is the Magma Design System's compact element for representing a discrete piece of information, a filter, a selection, or a removable token. It renders a label with optional leading icon and an optional delete affordance, and can be made interactive (clickable or selectable) to act as a lightweight button-like control rather than a static tag.\n\n#### Semantic Behavior\n\n- **Static by default**: With no interaction props the chip is a passive, non-focusable label; it becomes a focusable, button-like control only when `clickable` is set.\n- **Selectable implies clickable**: Setting `selectable` automatically turns on `clickable`, so a selectable chip is always keyboard- and pointer-interactive.\n- **Selection toggle**: When `selectable`, activating the chip flips `selected`; an unselected chip carries no `selected` attribute (rather than `selected=\"false\"`).\n- **Keyboard activation**: When interactive, Enter and Space activate the chip just like a pointer click.\n- **Delete affordance**: When `deletable`, a trailing delete button is rendered with a localized title (el/en/es/it) and emits the delete event on activation.\n- **Emitted events**: `mdsChipClickLabel` fires on activation for non-selectable chips, `mdsChipSelect` fires (carrying the new `selected` value) for selectable chips, and `mdsChipDelete` fires from the delete button - all carrying the originating event and host element.\n- **Label is text, on one line**: Long labels do not wrap (`truncate=\"word\"` on the inner text).\n\n#### Properties & Visual Configurations\n\nThe shared `variant` / `tone` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md); the chip defaults to `variant=\"primary\"` and `tone=\"strong\"`, and accepts only the minimal `'strong'` / `'weak'` tone set. `variant` and `tone` paint the leading icon badge and the border of a selected chip; the body of the chip stays neutral for every variant.\n\n#### Other behavioral props\n\n- **`clickable`** opts the chip into interactivity (focus, keyboard and click handling) without changing its state on activation - use it for chips that act as actions rather than toggles.\n- **`selectable`** makes the chip a toggle whose `selected` state flips on each activation; pick it for filter/choice chips where the visual selected state matters.\n- **`selected`** drives the selected visual treatment and can be set externally to pre-select a chip; an unselected chip carries no attribute.\n- **`deletable`** adds the trailing cancel button for removable tokens; reserve it for chips the user is meant to dismiss.\n- **`icon`** is an SVG filename slug from the Magma icon library, shown decoratively to the left of the label.\n",
7422
- "2. Examples": "Correct and idiomatic ways to use the `<mds-chip>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Static Tag (Label Only)\n\nThe simplest form. Use the required `label` prop to display a read-only tag. With no interaction props the chip is passive and non-focusable.\n\n```html\n<mds-chip label=\"In lavorazione\" variant=\"warning\" tone=\"strong\"></mds-chip>\n```\n\n#### Variant and Tone for Semantic Emphasis\n\nPair the same `variant` with a different `tone` to express importance or category. Do not invent custom colors to dim or saturate. The variant paints the leading icon badge (and the border of a selected chip), not the body of the chip: give the chip an `icon` when its color has to carry meaning.\n\n```html\n<!-- Status chips -->\n<mds-chip label=\"Completato\" icon=\"mi/baseline/check-circle\" variant=\"success\" tone=\"strong\"></mds-chip>\n<mds-chip label=\"In attesa\" icon=\"mi/baseline/schedule\" variant=\"warning\" tone=\"weak\"></mds-chip>\n<mds-chip label=\"Errore\" icon=\"mi/baseline/error\" variant=\"error\" tone=\"strong\"></mds-chip>\n\n<!-- Decorative label chips -->\n<mds-chip label=\"Natura\" icon=\"mi/baseline/eco\" variant=\"green\" tone=\"weak\"></mds-chip>\n<mds-chip label=\"Tecnologia\" icon=\"mi/baseline/computer\" variant=\"blue\" tone=\"strong\"></mds-chip>\n```\n\n#### Chip with Leading Icon\n\nReference icons by their filename slug (no `.svg` extension). The icon is rendered decoratively to the left of the label inside a circular badge.\n\n```html\n<mds-chip\n label=\"Animali\"\n icon=\"mi/baseline/pets\"\n variant=\"primary\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Clickable Chip (Action, No Toggle)\n\nUse `clickable` when the chip triggers an action but does not need a persistent selected state. The component adds `role=\"button\"`, focus handling, and keyboard activation. Listen for `mdsChipClickLabel`.\n\n```html\n<mds-chip\n label=\"Apri dettagli\"\n clickable\n icon=\"mi/baseline/open-in-new\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipClickLabel', (e) => {\n console.log('clicked', e.detail.element);\n });\n</script>\n```\n\n#### Selectable Chip (Toggle)\n\nUse `selectable` for filter or choice chips where the visual selected state matters. `selectable` implies `clickable` automatically. Activating the chip flips `selected`; the event `mdsChipSelect` carries the new value in `e.detail.selected` (`true`, or `undefined` when deselected).\n\n```html\n<mds-chip\n label=\"Vegetariano\"\n selectable\n icon=\"mi/baseline/eco\"\n variant=\"success\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipSelect', (e) => {\n console.log('selezionato:', e.detail.selected);\n });\n</script>\n```\n\n#### Pre-selected Chip\n\nSet `selected` externally to initialize a selectable chip in the selected state (e.g. when restoring saved filter state). An unselected chip carries no `selected` attribute.\n\n```html\n<mds-chip\n label=\"Urgente\"\n selectable\n selected\n variant=\"error\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Deletable Chip (Removable Token)\n\nUse `deletable` for chips the user is meant to dismiss - for example tags on an entity or active filters. A trailing cancel button emits `mdsChipDelete` on activation.\n\n```html\n<mds-chip\n label=\"Mario Rossi\"\n deletable\n icon=\"mi/baseline/person\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipDelete', (e) => {\n e.detail.element.remove();\n });\n</script>\n```\n\n#### Fully Interactive Chip\n\nCombine `clickable` (or `selectable`) with `deletable` for chips that can both be activated and removed independently.\n\n```html\n<mds-chip\n label=\"Sport invernali\"\n clickable\n deletable\n icon=\"mi/baseline/downhill-skiing\"\n variant=\"info\"\n tone=\"weak\"\n></mds-chip>\n```\n\n#### Disabled Chip\n\nSet `disabled` to dim the chip and block it: a clickable label leaves the tab order and takes `aria-disabled=\"true\"`, the delete button is disabled, and neither the pointer nor the keyboard fires an event. The prop is reflected, so setting it from code styles the chip too. Do not use `disabled=\"false\"` - remove the attribute to re-enable.\n\n```html\n<mds-chip\n label=\"Non disponibile\"\n disabled\n variant=\"dark\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Styling Customization\n\nStyle the chip only through its public `--mds-chip-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode, named themes and high contrast keep working. When `selected` is set the component swaps each property for a selected value of its own, which is not public. A property set on the host from outside wins over that swap: scope the resting values to `:not([selected])`, and set the same public properties on `[selected]` to restyle the selected state.\n\n```css\n.filtri-categoria mds-chip:not([selected]) {\n --mds-chip-background: rgb(var(--magma-accent-surface));\n --mds-chip-color: rgb(var(--magma-accent-fg));\n}\n\n.filtri-categoria mds-chip[selected] {\n --mds-chip-background: rgb(var(--magma-accent-emphasis));\n --mds-chip-color: rgb(var(--magma-accent-on-emphasis));\n}\n```\n",
7423
- "3. Mistakes": "Common incorrect uses of `<mds-chip>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Clickable Chip Without `clickable` or `selectable`\n\nWithout `clickable`, the chip has no `role`, no focus management, and no keyboard activation. Listening for click events on a static chip is a silent accessibility failure.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Apri\" variant=\"primary\" onclick=\"doSomething()\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Apri\" clickable variant=\"primary\"></mds-chip>\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipClickLabel', doSomething);\n</script>\n```\n\n#### Do Not Use `selected` Without `selectable`\n\n`selected` only has visual and semantic meaning when `selectable` is also set. On a non-selectable chip the attribute renders the selected style but the selection can never be toggled and no event fires, misleading users.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Attivo\" selected variant=\"success\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Attivo\" selectable selected variant=\"success\"></mds-chip>\n```\n\n#### Do Not Apply `tone` Values Outside the Minimal Ladder\n\n`mds-chip` accepts only `ToneMinimalVariantType`: `strong` and `weak`. Passing `outline`, `text`, or `box` is invalid: no style matches it, so the chip silently loses its variant colors.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Categoria\" tone=\"outline\" variant=\"primary\"></mds-chip>\n<mds-chip label=\"Categoria\" tone=\"text\" variant=\"primary\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Categoria\" tone=\"weak\" variant=\"primary\"></mds-chip>\n<mds-chip label=\"Categoria\" tone=\"strong\" variant=\"primary\"></mds-chip>\n```\n\n#### Do Not Slot Content Into the Chip\n\n`<mds-chip>` has no default or named slots - all content is driven by props (`label`, `icon`, `deletable`). Slotting HTML children is ignored by the Shadow DOM.\n\n```html\n<!-- INCORRECT -->\n<mds-chip>\n <span>Etichetta</span>\n <mds-icon name=\"mi/baseline/close\"></mds-icon>\n</mds-chip>\n\n<!-- CORRECT -->\n<mds-chip\n label=\"Etichetta\"\n icon=\"mi/baseline/pets\"\n deletable\n variant=\"primary\"\n></mds-chip>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Delete Button\n\nThe inner `mds-button` used for the delete affordance is a Shadow DOM implementation detail with no styling API of its own: targeting it with `>>>` or undocumented `::part()` names will break on minor releases. Restyle the chip and its leading icon through the public `--mds-chip-*` properties.\n\n```css\n/* INCORRECT */\nmds-chip >>> .button-delete {\n color: red;\n}\n\n/* CORRECT */\nmds-chip {\n --mds-chip-icon-background: rgb(var(--magma-danger-emphasis));\n}\n```\n\n#### Do Not Forget to Remove `await`-Pattern Analogue: Removing `selected` by Setting It to `false`\n\nWith `selected=\"false\"` the component reads the prop as `false` and drops the attribute when it renders, but until then the attribute is in the DOM and attribute selectors (`mds-chip[selected]`) match it. Remove the attribute; from JavaScript both `false` and `undefined` deselect the chip (the component turns `false` into `undefined` and drops the attribute).\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Filtro\" selectable selected=\"false\" variant=\"primary\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Filtro\" selectable variant=\"primary\"></mds-chip>\n```\n\n#### Do Not Use `<mds-chip>` as a Navigation Link\n\n`<mds-chip>` has no `href` prop. Wrapping it in an `<a>` creates a nested interactive element, breaks keyboard semantics, and fails accessibility audits. Use [`mds-button`](../mds-button/AGENTS.md) with `href` instead.\n\n```html\n<!-- INCORRECT -->\n<a href=\"/categoria/sport\">\n <mds-chip label=\"Sport\" variant=\"primary\"></mds-chip>\n</a>\n\n<!-- CORRECT -->\n<mds-button\n label=\"Sport\"\n href=\"/categoria/sport\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-button>\n```\n"
7809
+ "1. Description": "The `<mds-chip>` web component is the Magma Design System's compact element for representing a discrete piece of information, a filter, a selection, or a removable token. It renders a label with an optional leading icon or colour swatch and an optional delete affordance, and can be made interactive (clickable or selectable) to act as a lightweight button-like control rather than a static tag.\n\n#### Semantic Behavior\n\n- **Static by default**: With no interaction props the chip is a passive, non-focusable label; it becomes a focusable, button-like control only when `clickable` is set.\n- **Selectable implies clickable**: Setting `selectable` automatically turns on `clickable`, so a selectable chip is always keyboard- and pointer-interactive.\n- **Selection toggle**: When `selectable`, activating the chip flips `selected`; an unselected chip carries no `selected` attribute (rather than `selected=\"false\"`).\n- **Keyboard activation**: When interactive, Enter and Space activate the chip just like a pointer click.\n- **Delete affordance**: When `deletable`, a trailing delete button is rendered with a localized title (el/en/es/it) and emits the delete event on activation.\n- **Emitted events**: `mdsChipClickLabel` fires on activation for non-selectable chips, `mdsChipSelect` fires (carrying the new `selected` value) for selectable chips, and `mdsChipDelete` fires from the delete button - all carrying the originating event and host element.\n- **Label is text, on one line**: Long labels do not wrap (`truncate=\"word\"` on the inner text).\n- **One leading mark**: `swatch` takes the place of `icon`; when both are set the chip draws the swatch. The swatch is decorative and hidden from assistive technologies, so the label has to name the colour.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` / `tone` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md); the chip defaults to `variant=\"primary\"` and `tone=\"strong\"`, and accepts only the minimal `'strong'` / `'weak'` tone set. `variant` and `tone` paint the leading icon badge and the border of a selected chip; the body of the chip stays neutral for every variant.\n\n#### Other behavioral props\n\n- **`clickable`** opts the chip into interactivity (focus, keyboard and click handling) without changing its state on activation - use it for chips that act as actions rather than toggles.\n- **`selectable`** makes the chip a toggle whose `selected` state flips on each activation; pick it for filter/choice chips where the visual selected state matters.\n- **`selected`** drives the selected visual treatment and can be set externally to pre-select a chip; an unselected chip carries no attribute.\n- **`deletable`** adds the trailing cancel button for removable tokens; reserve it for chips the user is meant to dismiss.\n- **`icon`** is an SVG filename slug from the Magma icon library, shown decoratively to the left of the label.\n- **`swatch`** is a colour of the product, any CSS colour, drawn as a round swatch where the icon goes: for chips whose label names a colour (a family of colours, a category, a calendar). It is not a role and does not follow `variant` or the mode: the chip draws it as given, inside a ring that keeps it visible on the chip at rest and selected, in light and dark. A value that is not a colour draws the empty ring.\n",
7810
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-chip>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Static Tag (Label Only)\n\nThe simplest form. Use the required `label` prop to display a read-only tag. With no interaction props the chip is passive and non-focusable.\n\n```html\n<mds-chip label=\"In lavorazione\" variant=\"warning\" tone=\"strong\"></mds-chip>\n```\n\n#### Variant and Tone for Semantic Emphasis\n\nPair the same `variant` with a different `tone` to express importance or category. Do not invent custom colors to dim or saturate. The variant paints the leading icon badge (and the border of a selected chip), not the body of the chip: give the chip an `icon` when its color has to carry meaning.\n\n```html\n<!-- Status chips -->\n<mds-chip label=\"Completato\" icon=\"mi/baseline/check-circle\" variant=\"success\" tone=\"strong\"></mds-chip>\n<mds-chip label=\"In attesa\" icon=\"mi/baseline/schedule\" variant=\"warning\" tone=\"weak\"></mds-chip>\n<mds-chip label=\"Errore\" icon=\"mi/baseline/error\" variant=\"error\" tone=\"strong\"></mds-chip>\n\n<!-- Decorative label chips -->\n<mds-chip label=\"Natura\" icon=\"mi/baseline/eco\" variant=\"green\" tone=\"weak\"></mds-chip>\n<mds-chip label=\"Tecnologia\" icon=\"mi/baseline/computer\" variant=\"blue\" tone=\"strong\"></mds-chip>\n```\n\n#### Chip with Leading Icon\n\nReference icons by their filename slug (no `.svg` extension). The icon is rendered decoratively to the left of the label inside a circular badge.\n\n```html\n<mds-chip\n label=\"Animali\"\n icon=\"mi/baseline/pets\"\n variant=\"primary\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Chip with a Colour Swatch\n\nUse `swatch` when the label names a colour of the product: a family of colours to turn on and off, a category, a calendar. The value is the product's own, any CSS colour (`#a89586`, `rgb(47 111 208)`, `oklch(70% 0.19 50)`), not a token: the chip draws it as given in every mode, round and where the icon goes, inside a ring that keeps a colour as light or as dark as the chip visible. The swatch is hidden from assistive technologies, so the label names the colour; it takes the place of `icon`.\n\n```html\n<mds-chip label=\"kaolin\" swatch=\"#9aa3ad\" selectable selected></mds-chip>\n<mds-chip label=\"fireclay\" swatch=\"#a89586\" selectable></mds-chip>\n<mds-chip label=\"Calendario ferie\" swatch=\"#2f6fd0\" clickable></mds-chip>\n```\n\n#### Clickable Chip (Action, No Toggle)\n\nUse `clickable` when the chip triggers an action but does not need a persistent selected state. The component adds `role=\"button\"`, focus handling, and keyboard activation. Listen for `mdsChipClickLabel`.\n\n```html\n<mds-chip\n label=\"Apri dettagli\"\n clickable\n icon=\"mi/baseline/open-in-new\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipClickLabel', (e) => {\n console.log('clicked', e.detail.element);\n });\n</script>\n```\n\n#### Selectable Chip (Toggle)\n\nUse `selectable` for filter or choice chips where the visual selected state matters. `selectable` implies `clickable` automatically. Activating the chip flips `selected`; the event `mdsChipSelect` carries the new value in `e.detail.selected` (`true`, or `undefined` when deselected).\n\n```html\n<mds-chip\n label=\"Vegetariano\"\n selectable\n icon=\"mi/baseline/eco\"\n variant=\"success\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipSelect', (e) => {\n console.log('selezionato:', e.detail.selected);\n });\n</script>\n```\n\n#### Pre-selected Chip\n\nSet `selected` externally to initialize a selectable chip in the selected state (e.g. when restoring saved filter state). An unselected chip carries no `selected` attribute.\n\n```html\n<mds-chip\n label=\"Urgente\"\n selectable\n selected\n variant=\"error\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Deletable Chip (Removable Token)\n\nUse `deletable` for chips the user is meant to dismiss - for example tags on an entity or active filters. A trailing cancel button emits `mdsChipDelete` on activation.\n\n```html\n<mds-chip\n label=\"Mario Rossi\"\n deletable\n icon=\"mi/baseline/person\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipDelete', (e) => {\n e.detail.element.remove();\n });\n</script>\n```\n\n#### Fully Interactive Chip\n\nCombine `clickable` (or `selectable`) with `deletable` for chips that can both be activated and removed independently.\n\n```html\n<mds-chip\n label=\"Sport invernali\"\n clickable\n deletable\n icon=\"mi/baseline/downhill-skiing\"\n variant=\"info\"\n tone=\"weak\"\n></mds-chip>\n```\n\n#### Disabled Chip\n\nSet `disabled` to dim the chip and block it: a clickable label leaves the tab order and takes `aria-disabled=\"true\"`, the delete button is disabled, and neither the pointer nor the keyboard fires an event. The prop is reflected, so setting it from code styles the chip too. Do not use `disabled=\"false\"` - remove the attribute to re-enable.\n\n```html\n<mds-chip\n label=\"Non disponibile\"\n disabled\n variant=\"dark\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Styling Customization\n\nStyle the chip only through its public `--mds-chip-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode, named themes and high contrast keep working. When `selected` is set the component swaps each property for a selected value of its own, which is not public. A property set on the host from outside wins over that swap: scope the resting values to `:not([selected])`, and set the same public properties on `[selected]` to restyle the selected state.\n\n```css\n.filtri-categoria mds-chip:not([selected]) {\n --mds-chip-background: rgb(var(--magma-accent-surface));\n --mds-chip-color: rgb(var(--magma-accent-fg));\n}\n\n.filtri-categoria mds-chip[selected] {\n --mds-chip-background: rgb(var(--magma-accent-emphasis));\n --mds-chip-color: rgb(var(--magma-accent-on-emphasis));\n}\n```\n",
7811
+ "3. Mistakes": "Common incorrect uses of `<mds-chip>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Clickable Chip Without `clickable` or `selectable`\n\nWithout `clickable`, the chip has no `role`, no focus management, and no keyboard activation. Listening for click events on a static chip is a silent accessibility failure.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Apri\" variant=\"primary\" onclick=\"doSomething()\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Apri\" clickable variant=\"primary\"></mds-chip>\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipClickLabel', doSomething);\n</script>\n```\n\n#### Do Not Use `selected` Without `selectable`\n\n`selected` only has visual and semantic meaning when `selectable` is also set. On a non-selectable chip the attribute renders the selected style but the selection can never be toggled and no event fires, misleading users.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Attivo\" selected variant=\"success\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Attivo\" selectable selected variant=\"success\"></mds-chip>\n```\n\n#### Do Not Apply `tone` Values Outside the Minimal Ladder\n\n`mds-chip` accepts only `ToneMinimalVariantType`: `strong` and `weak`. Passing `outline`, `text`, or `box` is invalid: no style matches it, so the chip silently loses its variant colors.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Categoria\" tone=\"outline\" variant=\"primary\"></mds-chip>\n<mds-chip label=\"Categoria\" tone=\"text\" variant=\"primary\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Categoria\" tone=\"weak\" variant=\"primary\"></mds-chip>\n<mds-chip label=\"Categoria\" tone=\"strong\" variant=\"primary\"></mds-chip>\n```\n\n#### Do Not Slot Content Into the Chip\n\n`<mds-chip>` has no default or named slots - all content is driven by props (`label`, `icon`, `swatch`, `deletable`). Slotting HTML children is ignored by the Shadow DOM.\n\n```html\n<!-- INCORRECT -->\n<mds-chip>\n <span>Etichetta</span>\n <mds-icon name=\"mi/baseline/close\"></mds-icon>\n</mds-chip>\n\n<!-- CORRECT -->\n<mds-chip\n label=\"Etichetta\"\n icon=\"mi/baseline/pets\"\n deletable\n variant=\"primary\"\n></mds-chip>\n```\n\n#### Do Not Draw a Colour Through the Icon\n\nA circle icon painted with the colour, or the markup of an `<svg>` given to `icon`, sits on the disc of the icon, has no ring to keep a colour as light or as dark as the chip visible, and leans on custom properties that are not public. Give the colour to `swatch`.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"fireclay\" icon=\"mdi/circle\" style=\"--mds-chip-icon-color: #a89586\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"fireclay\" swatch=\"#a89586\"></mds-chip>\n```\n\n#### Do Not Say a State With a Swatch\n\nThe swatch draws its colour as given: a status painted there does not follow the mode, the named theme or the contrast preference as a variant does, and, hidden from assistive technologies, it adds nothing a screen reader hears. Say a status with `variant` and an icon; keep `swatch` for a colour the label names.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Errore\" swatch=\"#d32f2f\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Errore\" icon=\"mi/baseline/error\" variant=\"error\" tone=\"strong\"></mds-chip>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Delete Button\n\nThe inner `mds-button` used for the delete affordance is a Shadow DOM implementation detail with no styling API of its own: targeting it with `>>>` or undocumented `::part()` names will break on minor releases. Restyle the chip and its leading icon through the public `--mds-chip-*` properties.\n\n```css\n/* INCORRECT */\nmds-chip >>> .button-delete {\n color: red;\n}\n\n/* CORRECT */\nmds-chip {\n --mds-chip-icon-background: rgb(var(--magma-danger-emphasis));\n}\n```\n\n#### Do Not Forget to Remove `await`-Pattern Analogue: Removing `selected` by Setting It to `false`\n\nWith `selected=\"false\"` the component reads the prop as `false` and drops the attribute when it renders, but until then the attribute is in the DOM and attribute selectors (`mds-chip[selected]`) match it. Remove the attribute; from JavaScript both `false` and `undefined` deselect the chip (the component turns `false` into `undefined` and drops the attribute).\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Filtro\" selectable selected=\"false\" variant=\"primary\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Filtro\" selectable variant=\"primary\"></mds-chip>\n```\n\n#### Do Not Use `<mds-chip>` as a Navigation Link\n\n`<mds-chip>` has no `href` prop. Wrapping it in an `<a>` creates a nested interactive element, breaks keyboard semantics, and fails accessibility audits. Use [`mds-button`](../mds-button/AGENTS.md) with `href` instead.\n\n```html\n<!-- INCORRECT -->\n<a href=\"/categoria/sport\">\n <mds-chip label=\"Sport\" variant=\"primary\"></mds-chip>\n</a>\n\n<!-- CORRECT -->\n<mds-button\n label=\"Sport\"\n href=\"/categoria/sport\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-button>\n```\n"
7424
7812
  },
7425
7813
  "props": [
7426
7814
  {
@@ -7614,6 +8002,37 @@
7614
8002
  "getter": false,
7615
8003
  "setter": false
7616
8004
  },
8005
+ {
8006
+ "name": "swatch",
8007
+ "type": "string | undefined",
8008
+ "complexType": {
8009
+ "original": "string",
8010
+ "resolved": "string | undefined",
8011
+ "references": {}
8012
+ },
8013
+ "mutable": false,
8014
+ "attr": "swatch",
8015
+ "reflectToAttr": false,
8016
+ "docs": "A colour drawn as a round swatch where the icon goes, in place of `icon`: any CSS colour\n(`#2f6fd0`, `rgb(47 111 208)`, `oklch(55% 0.2 260)`). It is a value of the product, the\ncolour the label names (a family of colours, a category, a calendar), not a role of Magma:\nthe chip draws it as it is given in every mode and theme, inside a ring that keeps it visible\non the chip, at rest and selected. Decorative: hidden from assistive technologies, since the\nlabel names it. A value that is not a colour draws the empty ring.",
8017
+ "docsTags": [
8018
+ {
8019
+ "name": "example",
8020
+ "text": "'#2f6fd0'"
8021
+ }
8022
+ ],
8023
+ "values": [
8024
+ {
8025
+ "type": "string"
8026
+ },
8027
+ {
8028
+ "type": "undefined"
8029
+ }
8030
+ ],
8031
+ "optional": true,
8032
+ "required": false,
8033
+ "getter": false,
8034
+ "setter": false
8035
+ },
7617
8036
  {
7618
8037
  "name": "tone",
7619
8038
  "type": "\"strong\" | \"weak\" | undefined",
@@ -7940,8 +8359,8 @@
7940
8359
  "mds-button"
7941
8360
  ],
7942
8361
  "mds-button": [
7943
- "mds-spinner",
7944
8362
  "mds-icon",
8363
+ "mds-spinner",
7945
8364
  "mds-text"
7946
8365
  ],
7947
8366
  "mds-policy-ai": [
@@ -8121,7 +8540,7 @@
8121
8540
  "usage": {
8122
8541
  "1. Description": "The `<mds-dropdown>` web component is a floating overlay surface of the Magma Design System that anchors arbitrary slotted content next to an external trigger element. It has no built-in trigger of its own: it attaches to a separate caller resolved via `target` and positions, flips and shifts itself around that element.\n\n#### Semantic Behavior\n\n- **Caller binding**: The dropdown does not render a trigger; it resolves its caller from the `target` selector and wires the chosen interaction onto that external element. Changing `target` re-binds the caller.\n- **Visibility is the single source of truth**: The `visible` prop drives the whole lifecycle - it positions the floating element, optionally shows the backdrop, and emits the events; setting it back to `false` dismisses it.\n- **Outside-click dismissal**: While open, clicking outside both the host and the caller closes the dropdown.\n- **Escape to close**: Pressing Escape hides the dropdown, and hands the focus back to the caller when the panel was holding it.\n- **Keyboard, when the panel is a `menu`**: the arrows on the caller open the panel and land on the first entry (Up on the last), Enter does the same; inside the panel the arrows walk the entries and wrap at the ends, Home and End go to the first and to the last, Tab closes and lets the focus leave from the caller. A panel that declares another role is left alone: the arrows of a calendar or of a form belong to what the panel holds.\n- **Backdrop**: When `backdrop` is set, a backdrop is shown while the dropdown is visible and removed on close.\n- **Emitted events**: `mdsDropdownChange` fires on every visibility transition; `mdsDropdownVisible` and `mdsDropdownHide` fire on open and close respectively. Each detail carries the resolved `caller` and the current `visible` state.\n- **Default slot is the panel content**: Anything in the default slot (text, HTML, or other components) is the surface shown when the dropdown is triggered.\n- **ARIA wiring**: The panel declares itself a `menu` and names the elements the slot receives as its entries (`role=\"menuitem\"`, a role of their own other than `button` being left alone); the caller receives `aria-haspopup`, an `aria-controls` pointing at the panel and an `aria-expanded` that follows `visible`. A panel that is not a list of actions declares its own `role` in the markup and keeps it, its contents then being left alone. A caller that exposes no role of its own - a generic host that keeps its control inside its shadow root, such as `mds-tab-item` - is left unwired, none of those attributes being valid on it.\n\n#### Properties & Visual Configurations\n\n- **`interaction`** decides how the caller opens the panel: `'click'` toggles on caller click (with outside-click and Escape dismissal), `'mouseover'` opens on hover and closes on mouse leave, and `'none'` wires nothing on the caller, so visibility is controlled programmatically through `visible` (an open panel still closes on outside click and Escape).\n- **`target`** (required) is the CSS selector of the external element the dropdown attaches to and positions against.\n\n#### Other behavioral props\n\n- **`placement`** sets the side relative to the caller, taken whenever it has room: by default (auto-placement) the panel moves to the opposite side, then to the sides across, only when it does not fit there. **`disableAutoPlacement`** pins it to `placement`, and **`flip`** then allows the fallback to the opposite side only. The panel is shifted to stay inside the viewport with a safe margin by default - **`disableShift`** opts out of this and **`shiftPadding`** tunes the margin.\n- **`offset`** controls the gap between the panel and the caller; the pointer toward the caller is shown by default (**`hideArrow`** removes it) and **`arrowPadding`** insets it from the panel edges.\n- the panel tracks the caller smoothly as the page scrolls by default (**`disableSmooth`** opts out); **`strategy`** chooses the CSS positioning mode (`'absolute'` vs `'fixed'`) and **`zIndex`** sets the stacking order.\n",
8123
8542
  "2. Examples": "Correct and idiomatic ways to use the `<mds-dropdown>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Dropdown Menu\n\nThe minimal required setup: a trigger element with a unique `id` and a `<mds-dropdown>` with `target` pointing at it. The dropdown binds to the caller on `click` by default and dismisses on outside-click or Escape.\n\n```html\n<mds-button id=\"menu-utente\" label=\"Profilo\" icon=\"mi/baseline/account-circle\" variant=\"primary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#menu-utente\">\n <mds-button icon=\"mi/baseline/settings\" variant=\"dark\" tone=\"text\" label=\"Impostazioni account\"></mds-button>\n <mds-button icon=\"mi/baseline/logout\" variant=\"error\" tone=\"text\" label=\"Esci\"></mds-button>\n</mds-dropdown>\n```\n\n#### Panel That Is Not a Menu\n\nThe dropdown is a `menu` by default, a list of actions being what it holds most of the time. A panel that holds anything else - a calendar, a form, a paragraph with a link - declares its own `role`, which the component never overwrites: its contents are then left alone instead of being named entries of a menu.\n\n```html\n<mds-button id=\"info-policy\" label=\"Come usiamo i tuoi dati\" variant=\"primary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#info-policy\" role=\"group\">\n <mds-text typography=\"tip\">I dati restano sui server di Maggioli.</mds-text>\n <mds-button href=\"/policy\" label=\"Leggi la policy\" variant=\"dark\" tone=\"text\" size=\"sm\"></mds-button>\n</mds-dropdown>\n```\n\n#### Dropdown with Arrow Pointer\n\nThe arrow pointer is shown by default to visually connect the panel to its caller; add `hide-arrow` to remove it. Adjust `arrow-padding` when the panel is narrow and the arrow would clip the rounded corners.\n\n```html\n<mds-button id=\"aiuto-contestuale\" label=\"Aiuto\" icon=\"mi/baseline/help-outline\" variant=\"primary\" tone=\"outline\"></mds-button>\n\n<mds-dropdown target=\"#aiuto-contestuale\" arrow-padding=\"16\">\n <mds-text typography=\"h6\">Come funziona?</mds-text>\n <mds-text typography=\"detail\">Seleziona un campo per vedere la guida contestuale.</mds-text>\n</mds-dropdown>\n```\n\n#### Dropdown with Backdrop\n\nUse `backdrop` to dim the rest of the page while the panel is open. This is appropriate for panels with a higher modal weight, such as user-account menus or multi-step pickers.\n\nThe backdrop is appended to `<body>`, out of reach of the CSS inheritance of the dropdown: when it opens, the dropdown hands it the value it resolves for `--mds-dropdown-backdrop-z-index` and its fade duration, by default the ones of the page backdrop (`--magma-backdrop-z-index`, `--magma-backdrop-animation-duration`). With the animation preference set to reduce, the backdrop appears and goes without a fade.\n\n```html\n<mds-button id=\"selezione-filtri\" label=\"Filtra risultati\" icon=\"mi/baseline/filter-list\" variant=\"primary\"></mds-button>\n\n<mds-dropdown target=\"#selezione-filtri\" backdrop>\n <mds-text typography=\"h6\">Filtra per categoria</mds-text>\n <mds-filter>\n <mds-filter-item label=\"Documenti\"></mds-filter-item>\n <mds-filter-item label=\"Immagini\"></mds-filter-item>\n <mds-filter-item label=\"Video\"></mds-filter-item>\n </mds-filter>\n</mds-dropdown>\n```\n\n#### Mouseover Interaction\n\nSet `interaction=\"mouseover\"` for navigation mega-menus or info tooltips that should open on hover. The component adds a configurable delay (default 0.5 s, controlled by `--mds-dropdown-mouseover-delay`) before opening and closing.\n\n```html\n<mds-button id=\"info-progetto\" label=\"Dettagli progetto\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-dropdown target=\"#info-progetto\" interaction=\"mouseover\">\n <mds-entity icon=\"mi/baseline/folder\">\n <mds-text>Progetto Alfa - In corso</mds-text>\n </mds-entity>\n</mds-dropdown>\n```\n\n#### Programmatic Control via `visible`\n\nSet `interaction=\"none\"` to disable automatic wiring and drive visibility yourself. This is useful when the trigger logic lives in app code - for example, opening on a keyboard shortcut or a programmatic state change.\n\n```html\n<mds-button id=\"apri-manuale\" label=\"Apri pannello\" variant=\"primary\"></mds-button>\n\n<mds-dropdown id=\"pannello-opzioni\" target=\"#apri-manuale\" interaction=\"none\">\n <mds-text typography=\"detail\">Pannello gestito dal codice applicativo.</mds-text>\n</mds-dropdown>\n\n<script>\n const dropdown = document.querySelector('#pannello-opzioni');\n document.querySelector('#apri-manuale').addEventListener('click', () => {\n dropdown.visible = !dropdown.visible;\n });\n</script>\n```\n\n#### Placement and Auto-Placement\n\nUse `placement` to choose the side of the caller the panel opens on. Auto-placement is on by default: the panel takes `placement` whenever it has room there, and moves to the opposite side, then to the sides across, only when it does not fit; add `disable-auto-placement` to pin the panel strictly to `placement`.\n\n```html\n<!-- Pinned right-start placement (auto-placement disabled) -->\n<mds-button id=\"azioni-riga\" label=\"Azioni\" icon=\"mi/baseline/more-vert\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-dropdown target=\"#azioni-riga\" placement=\"right-start\" disable-auto-placement>\n <mds-button icon=\"mi/baseline/edit\" variant=\"dark\" tone=\"text\" label=\"Modifica\"></mds-button>\n <mds-button icon=\"mi/baseline/delete\" variant=\"error\" tone=\"text\" label=\"Elimina\"></mds-button>\n</mds-dropdown>\n\n<!-- Auto-placement (default) for constrained viewports -->\n<mds-button id=\"opzioni-voce\" label=\"Opzioni\" variant=\"primary\" tone=\"weak\"></mds-button>\n<mds-dropdown target=\"#opzioni-voce\">\n <mds-button label=\"Duplica\" icon=\"mi/baseline/content-copy\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-dropdown>\n```\n\n#### Flip and Shift for Viewport Safety\n\nEnable `flip` together with `disable-auto-placement` to let the pinned panel jump to the opposite side, and to no other, when there is not enough space in the preferred direction; auto-placement already includes that fallback. Shifting the panel to keep it inside the viewport is on by default; tune the safe margin with `shift-padding` (or set `disable-shift` to opt out).\n\n```html\n<mds-button id=\"btn-edge\" label=\"Vicino al bordo\" variant=\"primary\"></mds-button>\n\n<mds-dropdown target=\"#btn-edge\" placement=\"top\" disable-auto-placement flip shift-padding=\"16\">\n <mds-text typography=\"detail\">Questo pannello si sposta automaticamente se manca spazio.</mds-text>\n</mds-dropdown>\n```\n\n#### Listening to Visibility Events\n\nListen for `mdsDropdownVisible`, `mdsDropdownHide`, or `mdsDropdownChange` to react to open/close transitions. Each event detail contains `caller` (the resolved trigger element) and `visible` (the new state).\n\n```html\n<mds-button id=\"btn-notifica\" label=\"Notifiche\" icon=\"mi/baseline/notifications\" variant=\"primary\"></mds-button>\n\n<mds-dropdown id=\"pannello-notifiche\" target=\"#btn-notifica\">\n <mds-text typography=\"detail\">Nessuna nuova notifica.</mds-text>\n</mds-dropdown>\n\n<script>\n document.querySelector('#pannello-notifiche').addEventListener('mdsDropdownVisible', (e) => {\n console.log('Aperto. Trigger:', e.detail.caller);\n });\n document.querySelector('#pannello-notifiche').addEventListener('mdsDropdownHide', () => {\n console.log('Chiuso.');\n });\n</script>\n```\n\n#### Strategy `fixed` Inside Scrolling or Stacked Containers\n\nUse `strategy=\"fixed\"` when the dropdown is placed inside a scroll container, a sticky header, or a modal. With `strategy=\"absolute\"` (the default) the panel may be clipped by `overflow: hidden` ancestors.\n\n```html\n<!-- Inside a modal or a sticky nav - use fixed positioning -->\n<mds-button id=\"menu-header\" label=\"Menu\" variant=\"primary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#menu-header\" strategy=\"fixed\">\n <mds-button label=\"Pagina principale\" icon=\"mi/baseline/home\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Impostazioni\" icon=\"mi/baseline/settings\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-dropdown>\n```\n\n#### DOM Placement at the Document Root\n\nPlace `<mds-dropdown>` as a direct child of `<body>` (or as close as possible to the root) when the caller lives deep inside a stacking context. Nesting the dropdown inside the same transformed or `overflow: hidden` ancestor as the caller can break positioning and backdrop rendering.\n\n```html\n<body>\n <!-- Trigger lives inside a complex layout -->\n <div class=\"app-layout\">\n <nav>\n <mds-button id=\"btn-profilo\" label=\"Profilo\" variant=\"primary\"></mds-button>\n </nav>\n </div>\n\n <!-- Dropdown is a sibling of the layout root, not nested inside it -->\n <mds-dropdown target=\"#btn-profilo\" strategy=\"fixed\" backdrop>\n <mds-text typography=\"h6\">Mario Rossi</mds-text>\n <mds-button label=\"Esci\" icon=\"mi/baseline/logout\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-dropdown>\n</body>\n```\n\n#### Styling Customization\n\nCustomize the dropdown only through its public `--mds-dropdown-*` CSS custom properties. Use the semantic color roles via `rgb(var(--magma-<role>))` to preserve dark-mode, named-theme and high-contrast behavior.\n\n```css\n.my-context mds-dropdown {\n --mds-dropdown-background: rgb(var(--magma-surface-overlay));\n --mds-dropdown-mouseover-delay: 0.2s;\n --mds-dropdown-z-index: 5000;\n}\n```\n",
8124
- "3. Mistakes": "Common incorrect uses of `<mds-dropdown>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Place the Dropdown Deep Inside a Scroll or Stacking Context\n\nNesting `<mds-dropdown>` inside a transformed, sticky, or `overflow: hidden` ancestor breaks floating positioning and backdrop rendering. Place it as close to `<body>` as the page structure allows, or switch to `strategy=\"fixed\"`.\n\n```html\n<!-- INCORRECT -->\n<div style=\"overflow: hidden; position: relative;\">\n <mds-button id=\"trigger\" label=\"Apri\" variant=\"primary\"></mds-button>\n <mds-dropdown target=\"#trigger\" backdrop>\n <mds-text>Contenuto</mds-text>\n </mds-dropdown>\n</div>\n\n<!-- CORRECT -->\n<div style=\"overflow: hidden; position: relative;\">\n <mds-button id=\"trigger\" label=\"Apri\" variant=\"primary\"></mds-button>\n</div>\n<mds-dropdown target=\"#trigger\" strategy=\"fixed\" backdrop>\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n```\n\n#### Do Not Use `visible=\"false\"` to Close the Dropdown\n\n`visible` is a boolean prop. The component reads the string `\"false\"` as `false` and drops the attribute when it renders, but until then the attribute is in the DOM and attribute selectors (`mds-dropdown[visible]`) match it. Remove the attribute or set the property to `false` in JavaScript to close it.\n\n```html\n<!-- INCORRECT -->\n<mds-dropdown target=\"#btn\" visible=\"false\">\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n\n<!-- CORRECT -->\n<mds-dropdown target=\"#btn\">\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n```\n\n```js\n// CORRECT - closing programmatically\ndocument.querySelector('mds-dropdown').visible = false;\n```\n\n#### Do Not Listen for Native `click` on the Target Instead of Dropdown Events\n\nThe dropdown manages its own interaction and emits `mdsDropdownVisible`, `mdsDropdownHide`, and `mdsDropdownChange`. Attaching a raw `click` listener to the caller can interfere with inside-click handling and may fire before the dropdown has updated its state.\n\n```html\n<!-- INCORRECT -->\n<mds-button id=\"btn-info\" label=\"Info\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#btn-info\">...</mds-dropdown>\n\n<script>\n // raw native event on the caller - races with dropdown internals\n document.querySelector('#btn-info').addEventListener('click', () => {\n console.log('cliccato');\n });\n</script>\n\n<!-- CORRECT -->\n<mds-button id=\"btn-info\" label=\"Info\" variant=\"primary\"></mds-button>\n<mds-dropdown id=\"dd-info\" target=\"#btn-info\">...</mds-dropdown>\n\n<script>\n document.querySelector('#dd-info').addEventListener('mdsDropdownVisible', (e) => {\n console.log('dropdown aperto', e.detail.visible);\n });\n</script>\n```\n\n#### Do Not Use `target` Without a Matching Element in the DOM\n\n`target` is resolved with `querySelector` at `componentDidLoad` time. If the selector does not match any element the dropdown has no caller and cannot position or open itself. Always verify the `id` is present in the DOM before the component loads.\n\n```html\n<!-- INCORRECT - typo: button has id \"btn-salva\", target points to \"#salva\" -->\n<mds-button id=\"btn-salva\" label=\"Salva\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#salva\">\n <mds-text>Opzioni di salvataggio</mds-text>\n</mds-dropdown>\n\n<!-- CORRECT -->\n<mds-button id=\"btn-salva\" label=\"Salva\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#btn-salva\">\n <mds-text>Opzioni di salvataggio</mds-text>\n</mds-dropdown>\n```\n\n#### Do Not Use `<mds-button-dropdown>` and `<mds-dropdown>` Interchangeably\n\n[`mds-button-dropdown`](../mds-button-dropdown/AGENTS.md) is a compound component that already embeds a trigger button and a dropdown. Use it for a simple action-button-plus-menu. Use `<mds-dropdown>` directly only when the caller is not an `mds-button`, or when you need full control over the trigger element.\n\n```html\n<!-- INCORRECT - re-implementing what mds-button-dropdown already does -->\n<mds-button id=\"btn-azioni\" label=\"Azioni\" icon=\"mi/baseline/expand-more\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#btn-azioni\">\n <mds-button label=\"Modifica\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-dropdown>\n\n<!-- CORRECT - use the dedicated compound component -->\n<mds-button-dropdown label=\"Azioni\" variant=\"primary\">\n <mds-button label=\"Modifica\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Customize via Undocumented Shadow Internals\n\nThe supported customization surface is the public `--mds-dropdown-*` CSS custom properties. Targeting internal elements via `::part()` on non-documented parts, `>>>`, or class-name selectors couples your code to the Shadow DOM structure and breaks on any internal refactor.\n\n```css\n/* INCORRECT */\nmds-dropdown::part(panel) {\n border: 2px solid red;\n}\nmds-dropdown >>> .arrow {\n display: none;\n}\n\n/* CORRECT */\nmds-dropdown {\n --mds-dropdown-background: rgb(var(--magma-surface-overlay));\n --mds-dropdown-z-index: 6000;\n}\n```\n"
8543
+ "3. Mistakes": "Common incorrect uses of `<mds-dropdown>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Place the Dropdown Deep Inside a Scroll or Stacking Context\n\nNesting `<mds-dropdown>` inside a transformed, sticky, or `overflow: hidden` ancestor breaks floating positioning and backdrop rendering. Place it as close to `<body>` as the page structure allows, or switch to `strategy=\"fixed\"`.\n\n```html\n<!-- INCORRECT -->\n<div style=\"overflow: hidden; position: relative;\">\n <mds-button id=\"trigger\" label=\"Apri\" variant=\"primary\"></mds-button>\n <mds-dropdown target=\"#trigger\" backdrop>\n <mds-text>Contenuto</mds-text>\n </mds-dropdown>\n</div>\n\n<!-- CORRECT -->\n<div style=\"overflow: hidden; position: relative;\">\n <mds-button id=\"trigger\" label=\"Apri\" variant=\"primary\"></mds-button>\n</div>\n<mds-dropdown target=\"#trigger\" strategy=\"fixed\" backdrop>\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n```\n\n#### Do Not Use `visible=\"false\"` to Close the Dropdown\n\n`visible` is a boolean prop. The component reads the string `\"false\"` as `false` and drops the attribute when it renders, but until then the attribute is in the DOM and attribute selectors (`mds-dropdown[visible]`) match it. Remove the attribute or set the property to `false` in JavaScript to close it.\n\n```html\n<!-- INCORRECT -->\n<mds-dropdown target=\"#btn\" visible=\"false\">\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n\n<!-- CORRECT -->\n<mds-dropdown target=\"#btn\">\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n```\n\n```js\n// CORRECT - closing programmatically\ndocument.querySelector('mds-dropdown').visible = false;\n```\n\n#### Do Not Listen for Native `click` on the Target Instead of Dropdown Events\n\nThe dropdown manages its own interaction and emits `mdsDropdownVisible`, `mdsDropdownHide`, and `mdsDropdownChange`. Attaching a raw `click` listener to the caller can interfere with inside-click handling and may fire before the dropdown has updated its state.\n\n```html\n<!-- INCORRECT -->\n<mds-button id=\"btn-info\" label=\"Info\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#btn-info\">...</mds-dropdown>\n\n<script>\n // raw native event on the caller - races with dropdown internals\n document.querySelector('#btn-info').addEventListener('click', () => {\n console.log('cliccato');\n });\n</script>\n\n<!-- CORRECT -->\n<mds-button id=\"btn-info\" label=\"Info\" variant=\"primary\"></mds-button>\n<mds-dropdown id=\"dd-info\" target=\"#btn-info\">...</mds-dropdown>\n\n<script>\n document.querySelector('#dd-info').addEventListener('mdsDropdownVisible', (e) => {\n console.log('dropdown aperto', e.detail.visible);\n });\n</script>\n```\n\n#### Do Not Use `target` Without a Matching Element in the DOM\n\n`target` is resolved with `querySelector` when the dropdown loads, again whenever `target` changes, and when the dropdown comes back to the page after being moved. If the selector does not match any element the dropdown has no caller and cannot position or open itself. Always verify the `id` is present in the DOM before the component loads.\n\n```html\n<!-- INCORRECT - typo: button has id \"btn-salva\", target points to \"#salva\" -->\n<mds-button id=\"btn-salva\" label=\"Salva\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#salva\">\n <mds-text>Opzioni di salvataggio</mds-text>\n</mds-dropdown>\n\n<!-- CORRECT -->\n<mds-button id=\"btn-salva\" label=\"Salva\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#btn-salva\">\n <mds-text>Opzioni di salvataggio</mds-text>\n</mds-dropdown>\n```\n\n#### Do Not Use `<mds-button-dropdown>` and `<mds-dropdown>` Interchangeably\n\n[`mds-button-dropdown`](../mds-button-dropdown/AGENTS.md) is a compound component that already embeds a trigger button and a dropdown. Use it for a simple action-button-plus-menu. Use `<mds-dropdown>` directly only when the caller is not an `mds-button`, or when you need full control over the trigger element.\n\n```html\n<!-- INCORRECT - re-implementing what mds-button-dropdown already does -->\n<mds-button id=\"btn-azioni\" label=\"Azioni\" icon=\"mi/baseline/expand-more\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#btn-azioni\">\n <mds-button label=\"Modifica\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-dropdown>\n\n<!-- CORRECT - use the dedicated compound component -->\n<mds-button-dropdown label=\"Azioni\" variant=\"primary\">\n <mds-button label=\"Modifica\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Customize via Undocumented Shadow Internals\n\nThe supported customization surface is the public `--mds-dropdown-*` CSS custom properties. Targeting internal elements via `::part()` on non-documented parts, `>>>`, or class-name selectors couples your code to the Shadow DOM structure and breaks on any internal refactor.\n\n```css\n/* INCORRECT */\nmds-dropdown::part(panel) {\n border: 2px solid red;\n}\nmds-dropdown >>> .arrow {\n display: none;\n}\n\n/* CORRECT */\nmds-dropdown {\n --mds-dropdown-background: rgb(var(--magma-surface-overlay));\n --mds-dropdown-z-index: 6000;\n}\n```\n"
8125
8544
  },
8126
8545
  "props": [
8127
8546
  {
@@ -9689,8 +10108,8 @@
9689
10108
  "mds-button"
9690
10109
  ],
9691
10110
  "mds-button": [
9692
- "mds-spinner",
9693
10111
  "mds-icon",
10112
+ "mds-spinner",
9694
10113
  "mds-text"
9695
10114
  ]
9696
10115
  },
@@ -10953,8 +11372,8 @@
10953
11372
  "mds-badge"
10954
11373
  ],
10955
11374
  "mds-button": [
10956
- "mds-spinner",
10957
11375
  "mds-icon",
11376
+ "mds-spinner",
10958
11377
  "mds-text"
10959
11378
  ],
10960
11379
  "mds-img": [
@@ -11235,9 +11654,9 @@
11235
11654
  }
11236
11655
  ],
11237
11656
  "usage": {
11238
- "1. Description": "The `<mds-filter-item>` web component is a single selectable option inside the [`<mds-filter>`](../mds-filter/AGENTS.md) container of the Magma Design System. It renders as a toggle button (icon, label, and an optional count badge) and acts as the toggleable unit that drives the parent's filter selection - it has no standalone HTML primitive equivalent.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-filter-item>` must be a direct slot child of `<mds-filter>`; it is not used standalone and should not be mixed with other child types.\n- **Self-toggling + event**: Clicking (or activating via the keyboard) flips `selected` and emits `mdsFilterItemSelect` with `{ id, selected }`. The `id` is the one set in the markup; an item without one gets `item-<index>` from the parent on load. The parent enforces single vs. multiple selection and re-emits `mdsFilterChange` with the aggregated value list.\n- **State owned with the parent**: `selected` doubles as a styling hook and as the flag the parent reads/writes - in single-select mode the parent clears the other items' selection, and on reset it clears the whole group. The parent also follows a `selected` set by the application, without emitting `mdsFilterChange`.\n- **Toggle button**: The host is a `button` whose `aria-pressed` follows `selected`. Its name is the `label` followed by the `count` as a number of results in the page language (the `lang` of `<html>`): \"Nuove, 11 results\" in English, \"Nuove, 11 risultati\" in Italian. An `aria-label` written on the host by the author stays.\n- **Keyboard activation**: Enter (and numpad Enter) and Space activate the item like a pointer click.\n- **Focus management**: The item is focusable unless `disabled`, in which case it drops out of the tab order.\n\n#### Properties & Visual Configurations\n\n- **`selected`**: The selection state of the item. Set it on initial markup to pre-select a filter, or at runtime from the application (a filter restored from the address, a clear button outside the bar): the parent follows, in single mode clearing the others.\n- **`value`**: The form/data value contributed to the parent's aggregated `mdsFilterChange` payload when the item is selected. Provide a meaningful value distinct from the human-readable `label`.\n- **`count`**: An optional badge showing how many results the filter would yield. Use it only when the count is meaningful to the user; omit it for purely categorical filters.\n- **`icon`**: Optional leading icon (an icon name string). Without a `label` the item is named after the last segment of the slug (`map` for `mi/baseline/map`); give it an `aria-label` of your own when the slug does not say what the filter does.\n- **`disabled`**: Blocks the item: it leaves the tab order, ignores clicks and keys, is announced as unavailable (`aria-disabled`) and is painted in the disabled text colour.\n",
11657
+ "1. Description": "The `<mds-filter-item>` web component is a single selectable option inside the [`<mds-filter>`](../mds-filter/AGENTS.md) container of the Magma Design System. It renders as a toggle button (icon, label, and an optional count badge) and acts as the toggleable unit that drives the parent's filter selection - it has no standalone HTML primitive equivalent.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-filter-item>` must be a direct slot child of `<mds-filter>`; it is not used standalone and should not be mixed with other child types.\n- **Self-toggling + event**: Clicking (or activating via the keyboard) flips `selected` and emits `mdsFilterItemSelect` with `{ id, selected }`. The `id` is the one set in the markup; an item without one gets `item-<index>` from the parent on load. The parent enforces single vs. multiple selection and re-emits `mdsFilterChange` with the aggregated value list.\n- **State owned with the parent**: `selected` doubles as a styling hook and as the flag the parent reads/writes - in single-select mode the parent clears the other items' selection, and on reset it clears the whole group. The parent also follows a `selected` set by the application, without emitting `mdsFilterChange`.\n- **Toggle button**: The host is a `button` whose `aria-pressed` follows `selected`. Its name is the `label` followed by the `count` as a number of results in the page language (the `lang` of `<html>`): \"Nuove, 11 results\" in English, \"Nuove, 11 risultati\" in Italian. The name contains the text the item shows, the label and the count as separate words, so a speech-input user can say what they see (WCAG 2.5.3, Label in Name). An `aria-label` written on the host by the author stays, as written: it must contain that text too, and follow the count when it changes.\n- **Keyboard activation**: Enter (and numpad Enter) and Space activate the item like a pointer click.\n- **Focus management**: The item is focusable unless `disabled`, in which case it drops out of the tab order.\n\n#### Properties & Visual Configurations\n\n- **`selected`**: The selection state of the item. Set it on initial markup to pre-select a filter, or at runtime from the application (a filter restored from the address, a clear button outside the bar): the parent follows, in single mode clearing the others.\n- **`value`**: The form/data value contributed to the parent's aggregated `mdsFilterChange` payload when the item is selected. Provide a meaningful value distinct from the human-readable `label`.\n- **`count`**: An optional badge showing how many results the filter would yield. Use it only when the count is meaningful to the user; omit it for purely categorical filters.\n- **`icon`**: Optional leading icon (an icon name string). Without a `label` the item is named after the last segment of the slug (`map` for `mi/baseline/map`); give it an `aria-label` of your own when the slug does not say what the filter does.\n- **`disabled`**: Blocks the item: it leaves the tab order, ignores clicks and keys, is announced as unavailable (`aria-disabled`) and is painted in the disabled text colour.\n",
11239
11658
  "2. Examples": "Correct and idiomatic ways to use the `<mds-filter-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Filter Group\n\nThe canonical form. Place one or more `<mds-filter-item>` elements as direct children of `<mds-filter>`. Every item requires a `label` (the visible text) and a `value` (the machine-readable token emitted by the parent's `mdsFilterChange` event).\n\n```html\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n <mds-filter-item label=\"In attesa\" value=\"pending\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Pre-selecting an Item on Load\n\nSet `selected` on an item in the initial markup to make it active before any user interaction. The parent reads `selected` on mount and reflects the aggregated state correctly.\n\n```html\n<mds-filter label=\"Categoria\">\n <mds-filter-item label=\"Tutti\" value=\"all\" selected></mds-filter-item>\n <mds-filter-item label=\"Notizie\" value=\"news\"></mds-filter-item>\n <mds-filter-item label=\"Eventi\" value=\"events\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Count Badge\n\nPass a `count` string to show how many results each filter would yield. Use it when the number is meaningful to the user; omit it for purely categorical filters to keep the UI uncluttered.\n\n```html\n<mds-filter label=\"Priorita\">\n <mds-filter-item label=\"Alta\" value=\"high\" count=\"12\"></mds-filter-item>\n <mds-filter-item label=\"Media\" value=\"medium\" count=\"34\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\" value=\"low\" count=\"5\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Icon-Only Item\n\nOmit `label` and provide only `icon`. Without a label the item is named after the last segment of the icon slug (`grid view` for `mi/baseline/grid-view`); an `aria-label` of your own takes its place and stays. Use a recognizable icon so the purpose is clear without text, and give each item an `aria-label` when the slug does not say what it filters.\n\n```html\n<mds-filter label=\"Vista\">\n <mds-filter-item aria-label=\"Griglia\" icon=\"mi/baseline/grid-view\" value=\"grid\"></mds-filter-item>\n <mds-filter-item aria-label=\"Elenco\" icon=\"mi/baseline/view-list\" value=\"list\"></mds-filter-item>\n <mds-filter-item aria-label=\"Mappa\" icon=\"mi/baseline/map\" value=\"map\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Item with Icon and Label\n\nCombine `icon` and `label` for a filter item that pairs a glyph with a text description.\n\n```html\n<mds-filter label=\"Tipo documento\">\n <mds-filter-item icon=\"mi/baseline/picture-as-pdf\" label=\"PDF\" value=\"pdf\"></mds-filter-item>\n <mds-filter-item icon=\"mi/baseline/image\" label=\"Immagini\" value=\"image\"></mds-filter-item>\n <mds-filter-item icon=\"mi/baseline/video-library\" label=\"Video\" value=\"video\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Multiple Selection\n\nAdd `multiple` to `<mds-filter>` to allow several items to be selected at the same time. The parent aggregates the selected `value`s into a comma-separated string and emits it via `mdsFilterChange`.\n\n```html\n<mds-filter label=\"Settore\" multiple>\n <mds-filter-item label=\"Sanita\" value=\"health\"></mds-filter-item>\n <mds-filter-item label=\"Istruzione\" value=\"education\"></mds-filter-item>\n <mds-filter-item label=\"Trasporti\" value=\"transport\"></mds-filter-item>\n <mds-filter-item label=\"Ambiente\" value=\"environment\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Listening for Selection Events\n\nListen to `mdsFilterItemSelect` on a single item for per-item reactions, or to `mdsFilterChange` on the parent for the aggregated selection. The event detail for `mdsFilterItemSelect` is `{ id: string, selected: boolean }`.\n\n```html\n<mds-filter id=\"tipo-filter\" label=\"Tipo\">\n <mds-filter-item label=\"Bozza\" value=\"draft\"></mds-filter-item>\n <mds-filter-item label=\"Pubblicato\" value=\"published\"></mds-filter-item>\n</mds-filter>\n\n<script>\n document.getElementById('tipo-filter').addEventListener('mdsFilterChange', (e) => {\n console.log('Valori selezionati:', e.detail.value);\n });\n</script>\n```\n\n#### Reset Affordance\n\nAdd `reset` to `<mds-filter>` to show an automatic reset button when at least one item is active. The button is rendered by the parent internally - no extra `<mds-filter-item>` is needed - and named in the page language (\"Clear filters\").\n\n```html\n<mds-filter label=\"Regione\" reset>\n <mds-filter-item label=\"Nord\" value=\"north\"></mds-filter-item>\n <mds-filter-item label=\"Centro\" value=\"center\"></mds-filter-item>\n <mds-filter-item label=\"Sud\" value=\"south\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Styling the Count Badge\n\n`<mds-filter-item>` has no public CSS custom property and no shadow part: the count badge takes its colours from the item's `selected` state. To restyle the bar the items sit in, set the public `--mds-filter-*` properties on the parent `<mds-filter>`; use the semantic color roles via `rgb(var(--magma-<role>))`.\n\n```css\n.priority-filter mds-filter {\n --mds-filter-items-background: rgb(var(--magma-wash-strong));\n --mds-filter-items-background-active: rgb(var(--magma-accent-surface));\n}\n```\n",
11240
- "3. Mistakes": "Common incorrect uses of `<mds-filter-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-filter-item>` Outside `<mds-filter>`\n\n`<mds-filter-item>` is a compound child component. Without its parent it has no selection management, no auto-scroll, and no `mdsFilterChange` aggregation. Always wrap it in `<mds-filter>`.\n\n```html\n<!-- INCORRECT -->\n<div class=\"my-filters\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</div>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Set `selected=\"false\"` to Deselect\n\n`selected` is a boolean prop: remove the attribute entirely to deselect, as for every boolean. The runtime happens to read the string `\"false\"` as `false`, but the attribute stays in the markup until the component renders, and HTML, `[selected]` selectors and `hasAttribute()` read a present attribute as set.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\" selected=\"false\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Omit `value`\n\n`value` is the machine-readable token the parent aggregates into `mdsFilterChange`. Without it the parent's event payload is empty or meaningless for consumers - always provide a distinct, meaningful value.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Priorita\">\n <mds-filter-item label=\"Alta\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Priorita\">\n <mds-filter-item label=\"Alta\" value=\"high\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\" value=\"low\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Slot Content Inside `<mds-filter-item>`\n\n`<mds-filter-item>` has no publicly documented default or named slots. Icon, label, and count are all props. Slotting arbitrary HTML has no effect - use the dedicated props instead.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Formato\">\n <mds-filter-item value=\"pdf\">\n <mds-icon name=\"mi/baseline/picture-as-pdf\"></mds-icon>\n PDF\n </mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Formato\">\n <mds-filter-item icon=\"mi/baseline/picture-as-pdf\" label=\"PDF\" value=\"pdf\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Listen for Native `click` Instead of `mdsFilterItemSelect`\n\nThe component handles its own toggle internally and emits `mdsFilterItemSelect` when selection changes. A native `click` listener added before the component has loaded runs before the internal toggle (listeners run in the order they were added), so it reads the old `selected` state.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n<script>\n document.querySelector('mds-filter-item[value=\"active\"]').addEventListener('click', (e) => {\n console.log('selected?', e.target.selected); // state not yet updated\n });\n</script>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n<script>\n document.querySelector('mds-filter-item[value=\"active\"]').addEventListener('mdsFilterItemSelect', (e) => {\n console.log('selected:', e.detail.selected);\n });\n</script>\n```\n\n#### Do Not Customize via Undocumented Shadow Parts or Internal Selectors\n\n`<mds-filter-item>` has no public CSS custom property and no shadow part: the count badge follows the `selected` state, and the bar is styled through the parent's public `--mds-filter-*` properties. Targeting shadow internals via `::part()`, `>>>`, or other selectors couples code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-filter-item >>> .count {\n border-radius: 4px;\n}\nmds-filter-item::part(count) {\n background: red;\n}\n\n/* CORRECT */\nmds-filter {\n --mds-filter-items-background: rgb(var(--magma-wash-strong));\n --mds-filter-items-background-active: rgb(var(--magma-accent-surface));\n}\n```\n"
11659
+ "3. Mistakes": "Common incorrect uses of `<mds-filter-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-filter-item>` Outside `<mds-filter>`\n\n`<mds-filter-item>` is a compound child component. Without its parent it has no selection management, no auto-scroll, and no `mdsFilterChange` aggregation. Always wrap it in `<mds-filter>`.\n\n```html\n<!-- INCORRECT -->\n<div class=\"my-filters\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</div>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Set `selected=\"false\"` to Deselect\n\n`selected` is a boolean prop: remove the attribute entirely to deselect, as for every boolean. The runtime happens to read the string `\"false\"` as `false`, but the attribute stays in the markup until the component renders, and HTML, `[selected]` selectors and `hasAttribute()` read a present attribute as set.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\" selected=\"false\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Omit `value`\n\n`value` is the machine-readable token the parent aggregates into `mdsFilterChange`. Without it the parent's event payload is empty or meaningless for consumers - always provide a distinct, meaningful value.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Priorita\">\n <mds-filter-item label=\"Alta\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Priorita\">\n <mds-filter-item label=\"Alta\" value=\"high\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\" value=\"low\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Leave the Count Out of an `aria-label` of Your Own\n\nThe item names itself after its label and its count. An `aria-label` written on the host replaces that name as it is, and the count the item shows is visible text too: a name without it fails WCAG 2.5.3 (Label in Name), and a speech-input user saying the number does not reach the item. Put the count in the name, or leave the name to the item.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Vista\">\n <mds-filter-item aria-label=\"Vista a griglia\" icon=\"mi/baseline/grid-view\" value=\"grid\" count=\"3\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Vista\">\n <mds-filter-item aria-label=\"Vista a griglia, 3 risultati\" icon=\"mi/baseline/grid-view\" value=\"grid\" count=\"3\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Slot Content Inside `<mds-filter-item>`\n\n`<mds-filter-item>` has no publicly documented default or named slots. Icon, label, and count are all props. Slotting arbitrary HTML has no effect - use the dedicated props instead.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Formato\">\n <mds-filter-item value=\"pdf\">\n <mds-icon name=\"mi/baseline/picture-as-pdf\"></mds-icon>\n PDF\n </mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Formato\">\n <mds-filter-item icon=\"mi/baseline/picture-as-pdf\" label=\"PDF\" value=\"pdf\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Listen for Native `click` Instead of `mdsFilterItemSelect`\n\nThe component handles its own toggle internally and emits `mdsFilterItemSelect` when selection changes. A native `click` listener added before the component has loaded runs before the internal toggle (listeners run in the order they were added), so it reads the old `selected` state.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n<script>\n document.querySelector('mds-filter-item[value=\"active\"]').addEventListener('click', (e) => {\n console.log('selected?', e.target.selected); // state not yet updated\n });\n</script>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n<script>\n document.querySelector('mds-filter-item[value=\"active\"]').addEventListener('mdsFilterItemSelect', (e) => {\n console.log('selected:', e.detail.selected);\n });\n</script>\n```\n\n#### Do Not Customize via Undocumented Shadow Parts or Internal Selectors\n\n`<mds-filter-item>` has no public CSS custom property and no shadow part: the count badge follows the `selected` state, and the bar is styled through the parent's public `--mds-filter-*` properties. Targeting shadow internals via `::part()`, `>>>`, or other selectors couples code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-filter-item >>> .count {\n border-radius: 4px;\n}\nmds-filter-item::part(count) {\n background: red;\n}\n\n/* CORRECT */\nmds-filter {\n --mds-filter-items-background: rgb(var(--magma-wash-strong));\n --mds-filter-items-background-active: rgb(var(--magma-accent-surface));\n}\n```\n"
11241
11660
  },
11242
11661
  "props": [
11243
11662
  {
@@ -11959,8 +12378,8 @@
11959
12378
  "mds-button"
11960
12379
  ],
11961
12380
  "mds-button": [
11962
- "mds-spinner",
11963
12381
  "mds-icon",
12382
+ "mds-spinner",
11964
12383
  "mds-text"
11965
12384
  ]
11966
12385
  },
@@ -12211,8 +12630,8 @@
12211
12630
  "mds-button"
12212
12631
  ],
12213
12632
  "mds-button": [
12214
- "mds-spinner",
12215
12633
  "mds-icon",
12634
+ "mds-spinner",
12216
12635
  "mds-text"
12217
12636
  ]
12218
12637
  },
@@ -12738,8 +13157,8 @@
12738
13157
  "mds-button"
12739
13158
  ],
12740
13159
  "mds-button": [
12741
- "mds-spinner",
12742
13160
  "mds-icon",
13161
+ "mds-spinner",
12743
13162
  "mds-text"
12744
13163
  ]
12745
13164
  },
@@ -12792,8 +13211,8 @@
12792
13211
  }
12793
13212
  ],
12794
13213
  "usage": {
12795
- "1. Description": "The `<mds-icon>` web component is the single glyph primitive of the Magma Design System: it inlines an SVG into the DOM so the artwork inherits color and sizing from CSS, and it is the building block that nearly every other component (button, chip, input, banner, list-item, etc.) composes to render its iconography. It replaces a raw `<img>`/`<svg>` tag and centralizes how icon artwork is resolved.\n\n#### Semantic Behavior\n\n- **Decorative by default**: The icon contributes no accessible name; meaning must come from the surrounding labelled control or text.\n- **Source resolution**: `name` is interpreted three ways - a string starting with `data:image/svg+xml;base64,` is decoded inline (as UTF-8; a payload that is not base64 draws nothing and logs a console warning), a markup string starting with the `<svg` element, or with the XML declaration, doctype or comments a saved `.svg` file opens with, is used verbatim, and anything else is treated as an icon filename slug fetched as `<svg directory><slug>.svg` (a name starting with `http` is fetched as it is). Without a `name` (attribute missing or empty, property `undefined` or `null`) the icon renders nothing, sends no request and logs nothing; removing `name` clears the icon.\n- **Async load**: When `name` is a slug the icon paints once the SVG arrives; a failed fetch renders empty rather than throwing. Only the latest `name` and SVG path count: a request that finishes after a newer one is discarded.\n- **Path configuration**: The SVG directory is set programmatically via the shared `IconsSetService.setSvgPath()` singleton (imported from `@maggioli-design-system/magma/services`), with the `mdsIconSvgPath` `sessionStorage` key as an optional fallback and the `setSvgPath` instance method as an alternative; icons that mounted before the path was configured reload themselves once it is set. An icon removed from the page stops listening for path changes; once it is put back it picks up a path set in the meantime.\n\n#### Properties & Visual Configurations\n\n- **`name`** is the only configurable input and is overloaded: pass an icon filename slug to pull artwork from the shared library, a base64-encoded SVG `data:` URI for inline/dynamic artwork, or a full raw SVG string when the markup is generated at runtime.\n\nThis component does not use the shared `variant` / `tone` / `size` ladders defined in [`agents/variants.md`](../../../../agents/variants.md); the color comes from the inherited CSS `fill` and the size from the host `width` (24px by default, the height follows the square aspect ratio), which is how parent components tint and scale their icons.\n",
12796
- "2. Examples": "Correct and idiomatic ways to use the `<mds-icon>` component, ordered from most common to most specialized. The examples assume a working knowledge of the icon slug conventions documented in [`agents/conventions.md`](../../../../agents/conventions.md) and the icon setup in [`agents/assets.md`](../../../../agents/assets.md).\n\n#### Icon Slug from the Shared Library\n\nThe canonical form. Pass a slug string as `name`; the component fetches the matching SVG from the configured assets directory. Slugs follow the convention of the active iconsauce plugin: `mi/<variant>/<name>` for Material Icons, `mdi/<name>` for Material Design Icons, and `mgg/<name>` for the internal Maggioli set.\n\n```html\n<!-- Material Icons baseline variant -->\n<mds-icon name=\"mi/baseline/search\"></mds-icon>\n\n<!-- Material Design Icons -->\n<mds-icon name=\"mdi/alien\"></mds-icon>\n\n<!-- Internal Maggioli set -->\n<mds-icon name=\"mgg/action-email-send-wait\"></mds-icon>\n```\n\n#### Configuring the SVG Base Path via `IconsSetService` (recommended)\n\nImport the shared `IconsSetService` singleton from the package's `services` entry point and call `setSvgPath()`. It updates the shared, in-memory icon path - kept on `globalThis` so every bundled copy of the service (lazy chunks, `esm`/`esm-es5` variants, `dist/components`) agrees on it - and notifies all mounted icons to (re)load immediately. **No `sessionStorage` is involved**, which makes it the safest option when storage is blocked (incognito, sandboxed iframes, storage partitioning). Pass an absolute path (starting with `/`) or a full URL. The icons are downloaded with `fetch`: under a Content Security Policy the origin of the path must be allowed by `connect-src` (or `default-src`), which `'self'` already does for a path on the page's own origin, while a CDN must be listed.\n\n```javascript\nimport { IconsSetService } from '@maggioli-design-system/magma/services';\n\nIconsSetService.setSvgPath('/assets/img/svg/');\n```\n\nIt can be called before or after the icons mount: instances mounted earlier re-fetch automatically once the path is set. Always use the exported `IconsSetService`; do not construct your own controller, which would keep a separate icon cache and listener list.\n\n#### Configuring the SVG Base Path via sessionStorage (optional)\n\nSet `mdsIconSvgPath` in `sessionStorage` before any `<mds-icon>` mounts; every icon instance falls back to this key when no path has been set programmatically. This one-liner is convenient but **may be blocked** by some browsers, privacy/incognito modes, storage partitioning, or sandboxed iframes - when that happens, use `IconsSetService.setSvgPath()` above instead.\n\n```javascript\nwindow.sessionStorage.setItem('mdsIconSvgPath', '/assets/img/svg/');\n```\n\n#### Forcing a Reload After Late Path Configuration\n\nIf icons are already in the DOM when the SVG path is set (for example, inside a lazy-loaded module), dispatch `mdsIconSvgPathUpdate` after configuring the path. Every mounted instance listens for this event and re-fetches.\n\n```javascript\nwindow.sessionStorage.setItem('mdsIconSvgPath', '/assets/img/svg/');\nwindow.dispatchEvent(new CustomEvent('mdsIconSvgPathUpdate'));\n```\n\n#### Configuring the SVG Base Path via the Instance Method\n\nAn alternative to `IconsSetService` when you already hold an `<mds-icon>` element: call its `setSvgPath` `@Method`. It delegates to the same singleton, so the effect is identical - prefer `IconsSetService` unless creating an element is more convenient (for example, in isolated testing environments).\n\n```javascript\nawait customElements.whenDefined('mds-icon');\nconst tmp = document.createElement('mds-icon');\ndocument.body.appendChild(tmp);\nif ('setSvgPath' in tmp) {\n tmp.setSvgPath('/assets/img/svg/');\n}\ndocument.body.removeChild(tmp);\n```\n\n#### Inline Raw SVG String\n\nPass a full SVG markup string as `name` when the artwork is generated or received at runtime and does not have a slug in the library. The component uses the string verbatim - no network request is made.\n\n```html\n<mds-icon\n name='<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path d=\"M12 2L2 22h20L12 2z\"/></svg>'\n></mds-icon>\n```\n\n#### Base64-encoded SVG Data URI\n\nPass a `data:image/svg+xml;base64,...` string when the icon is delivered from an API as a Base64 payload. The component decodes it inline, padding included - no external fetch occurs.\n\n```html\n<mds-icon name=\"data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTEyIDJMMiAyMmgyMHoiLz48L3N2Zz4=\"></mds-icon>\n```\n\n#### Sizing via CSS Width\n\n`<mds-icon>` is `display: inline-flex` with `aspect-ratio: 1` and a default width of `--spacing(600)`. Override size by setting a `width` on the host - height scales automatically via the aspect ratio. Use Magma spacing tokens to stay on-grid.\n\n```html\n<!-- Small icon using a Tailwind spacing utility -->\n<mds-icon name=\"mi/baseline/info\" class=\"w-400\"></mds-icon>\n\n<!-- Large icon -->\n<mds-icon name=\"mi/baseline/star\" class=\"w-1200\"></mds-icon>\n```\n\n#### Coloring via `fill` Utility or `currentColor`\n\nThe inlined SVG paints with the inherited CSS `fill`, so a Tailwind `fill-*` utility on the host, or `fill: currentColor` on a parent to follow its text color, is enough to tint the artwork; `color` alone does not tint it. Use Magma color roles, or a `label-*` colour for a category.\n\n```html\n<!-- Tint with a Magma label token -->\n<mds-icon name=\"mi/baseline/check-circle\" class=\"fill-label-green-06\"></mds-icon>\n\n<!-- Follow the current text color of a parent -->\n<p class=\"text-success-fg fill-current\">\n <mds-icon name=\"mi/baseline/check\"></mds-icon>\n Operazione completata\n</p>\n```\n\n#### Standalone Decorative Icon Inside a Labelled Control\n\n`<mds-icon>` renders with `aria-hidden=\"true\"` on its inner element; it carries no accessible name itself. When used standalone next to visible text, no extra ARIA is needed. When used as the only visual indicator inside an interactive control, the control must supply the accessible name.\n\n```html\n<!-- Decorative: the adjacent text provides the meaning -->\n<span class=\"flex items-center gap-200\">\n <mds-icon name=\"mi/baseline/email\"></mds-icon>\n Invia messaggio\n</span>\n```\n\n#### Styling via `::part(svg)`\n\nThe single documented shadow part is `svg` - the `<i>` wrapper around the inlined SVG. Use `::part(svg)` only for deep SVG styling not achievable through `fill` or `color`. Keep to documented parts; undocumented internals can change on minor releases.\n\n```css\nmds-icon::part(svg) {\n filter: drop-shadow(0 1px 2px rgb(var(--magma-shadow-ink) / 0.3));\n}\n```\n",
13214
+ "1. Description": "The `<mds-icon>` web component is the single glyph primitive of the Magma Design System: it inlines an SVG into the DOM so the artwork inherits color and sizing from CSS, and it is the building block that nearly every other component (button, chip, input, banner, list-item, etc.) composes to render its iconography. It replaces a raw `<img>`/`<svg>` tag and centralizes how icon artwork is resolved.\n\n#### Semantic Behavior\n\n- **Decorative by default**: The icon contributes no accessible name; meaning must come from the surrounding labelled control or text.\n- **Source resolution**: `name` is interpreted three ways - a string starting with `data:image/svg+xml;base64,` is decoded inline (as UTF-8; a payload that is not base64 draws nothing and logs a console warning), a markup string starting with the `<svg` element, or with the XML declaration, doctype or comments a saved `.svg` file opens with, is used verbatim, and anything else is treated as an icon filename slug fetched as `<svg directory><slug>.svg` (a name starting with `http` is fetched as it is). Without a `name` (attribute missing or empty, property `undefined` or `null`) the icon renders nothing, sends no request and logs nothing; removing `name` clears the icon.\n- **Async load**: When `name` is a slug the icon paints once the SVG arrives; a failed fetch renders empty rather than throwing. Only the latest `name` and SVG path count: a request that finishes after a newer one is discarded.\n- **Path configuration**: The SVG directory is set programmatically via the shared `IconsSetService.setSvgPath()` singleton (imported from `@maggioli-design-system/magma`), with the `mdsIconSvgPath` `sessionStorage` key as an optional fallback and the `setSvgPath` instance method as an alternative; icons that mounted before the path was configured reload themselves once it is set. An icon removed from the page stops listening for path changes; once it is put back it picks up a path set in the meantime.\n\n#### Properties & Visual Configurations\n\n- **`name`** is the only configurable input and is overloaded: pass an icon filename slug to pull artwork from the shared library, a base64-encoded SVG `data:` URI for inline/dynamic artwork, or a full raw SVG string when the markup is generated at runtime.\n\nThis component does not use the shared `variant` / `tone` / `size` ladders defined in [`agents/variants.md`](../../../../agents/variants.md); the color comes from the inherited CSS `fill` and the size from the host `width` (24px by default, the height follows the square aspect ratio), which is how parent components tint and scale their icons.\n",
13215
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-icon>` component, ordered from most common to most specialized. The examples assume a working knowledge of the icon slug conventions documented in [`agents/conventions.md`](../../../../agents/conventions.md) and the icon setup in [`agents/assets.md`](../../../../agents/assets.md).\n\n#### Icon Slug from the Shared Library\n\nThe canonical form. Pass a slug string as `name`; the component fetches the matching SVG from the configured assets directory. Slugs follow the convention of the active iconsauce plugin: `mi/<variant>/<name>` for Material Icons, `mdi/<name>` for Material Design Icons, and `mgg/<name>` for the internal Maggioli set.\n\n```html\n<!-- Material Icons baseline variant -->\n<mds-icon name=\"mi/baseline/search\"></mds-icon>\n\n<!-- Material Design Icons -->\n<mds-icon name=\"mdi/alien\"></mds-icon>\n\n<!-- Internal Maggioli set -->\n<mds-icon name=\"mgg/action-email-send-wait\"></mds-icon>\n```\n\n#### Configuring the SVG Base Path via `IconsSetService` (recommended)\n\nImport the shared `IconsSetService` singleton from the package root, `@maggioli-design-system/magma` (`@maggioli-design-system/magma/services` is the same module), and call `setSvgPath()`. It updates the shared, in-memory icon path - kept on `globalThis` so every bundled copy of the service (lazy chunks, `esm`/`esm-es5` variants, `dist/components`) agrees on it - and notifies all mounted icons to (re)load immediately. **No `sessionStorage` is involved**, which makes it the safest option when storage is blocked (incognito, sandboxed iframes, storage partitioning). Pass an absolute path (starting with `/`) or a full URL. The icons are downloaded with `fetch`: under a Content Security Policy the origin of the path must be allowed by `connect-src` (or `default-src`), which `'self'` already does for a path on the page's own origin, while a CDN must be listed.\n\n```javascript\nimport { IconsSetService } from '@maggioli-design-system/magma';\n\nIconsSetService.setSvgPath('/assets/img/svg/');\n```\n\nIt can be called before or after the icons mount: instances mounted earlier re-fetch automatically once the path is set. A path set this way wins over the `mdsIconSvgPath` key of `sessionStorage`, read before or after it. On a server (no `window`) the call stores nothing: with SSR, call it in code the browser runs. Always use the exported `IconsSetService`; do not construct your own controller, which would keep a separate icon cache and listener list.\n\n#### Configuring the SVG Base Path via sessionStorage (optional)\n\nSet `mdsIconSvgPath` in `sessionStorage` before any `<mds-icon>` mounts; every icon instance falls back to this key when no path has been set programmatically. This one-liner is convenient but **may be blocked** by some browsers, privacy/incognito modes, storage partitioning, or sandboxed iframes - when that happens, use `IconsSetService.setSvgPath()` above instead.\n\n```javascript\nwindow.sessionStorage.setItem('mdsIconSvgPath', '/assets/img/svg/');\n```\n\n#### Forcing a Reload After Late Path Configuration\n\nIf icons are already in the DOM when the SVG path is set (for example, inside a lazy-loaded module), dispatch `mdsIconSvgPathUpdate` after configuring the path. Every mounted instance listens for this event and re-fetches.\n\n```javascript\nwindow.sessionStorage.setItem('mdsIconSvgPath', '/assets/img/svg/');\nwindow.dispatchEvent(new CustomEvent('mdsIconSvgPathUpdate'));\n```\n\n#### Configuring the SVG Base Path via the Instance Method\n\nAn alternative to `IconsSetService` when you already hold an `<mds-icon>` element: call its `setSvgPath` `@Method`. It delegates to the same singleton, so the effect is identical - prefer `IconsSetService` unless creating an element is more convenient (for example, in isolated testing environments).\n\n```javascript\nawait customElements.whenDefined('mds-icon');\nconst tmp = document.createElement('mds-icon');\ndocument.body.appendChild(tmp);\nif ('setSvgPath' in tmp) {\n tmp.setSvgPath('/assets/img/svg/');\n}\ndocument.body.removeChild(tmp);\n```\n\n#### Inline Raw SVG String\n\nPass a full SVG markup string as `name` when the artwork is generated or received at runtime and does not have a slug in the library. The component uses the string verbatim - no network request is made.\n\n```html\n<mds-icon\n name='<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path d=\"M12 2L2 22h20L12 2z\"/></svg>'\n></mds-icon>\n```\n\n#### Base64-encoded SVG Data URI\n\nPass a `data:image/svg+xml;base64,...` string when the icon is delivered from an API as a Base64 payload. The component decodes it inline, padding included - no external fetch occurs.\n\n```html\n<mds-icon name=\"data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTEyIDJMMiAyMmgyMHoiLz48L3N2Zz4=\"></mds-icon>\n```\n\n#### Sizing via CSS Width\n\n`<mds-icon>` is `display: inline-flex` with `aspect-ratio: 1` and a default width of `--spacing(600)`. Override size by setting a `width` on the host - height scales automatically via the aspect ratio. Use Magma spacing tokens to stay on-grid.\n\n```html\n<!-- Small icon using a Tailwind spacing utility -->\n<mds-icon name=\"mi/baseline/info\" class=\"w-400\"></mds-icon>\n\n<!-- Large icon -->\n<mds-icon name=\"mi/baseline/star\" class=\"w-1200\"></mds-icon>\n```\n\n#### Coloring via `fill` Utility or `currentColor`\n\nThe inlined SVG paints with the inherited CSS `fill`, so a Tailwind `fill-*` utility on the host, or `fill: currentColor` on a parent to follow its text color, is enough to tint the artwork; `color` alone does not tint it. Use Magma color roles, or a `label-*` colour for a category.\n\n```html\n<!-- Tint with a Magma label token -->\n<mds-icon name=\"mi/baseline/check-circle\" class=\"fill-label-green-06\"></mds-icon>\n\n<!-- Follow the current text color of a parent -->\n<p class=\"text-success-fg fill-current\">\n <mds-icon name=\"mi/baseline/check\"></mds-icon>\n Operazione completata\n</p>\n```\n\n#### Standalone Decorative Icon Inside a Labelled Control\n\n`<mds-icon>` renders with `aria-hidden=\"true\"` on its inner element; it carries no accessible name itself. When used standalone next to visible text, no extra ARIA is needed. When used as the only visual indicator inside an interactive control, the control must supply the accessible name.\n\n```html\n<!-- Decorative: the adjacent text provides the meaning -->\n<span class=\"flex items-center gap-200\">\n <mds-icon name=\"mi/baseline/email\"></mds-icon>\n Invia messaggio\n</span>\n```\n\n#### Styling via `::part(svg)`\n\nThe single documented shadow part is `svg` - the `<i>` wrapper around the inlined SVG. Use `::part(svg)` only for deep SVG styling not achievable through `fill` or `color`. Keep to documented parts; undocumented internals can change on minor releases.\n\n```css\nmds-icon::part(svg) {\n filter: drop-shadow(0 1px 2px rgb(var(--magma-shadow-ink) / 0.3));\n}\n```\n",
12797
13216
  "3. Mistakes": "Common incorrect uses of `<mds-icon>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<img>` or Inline `<svg>` Instead of `<mds-icon>`\n\nUsing a raw `<img src=\"...svg\">` or a hardcoded `<svg>` literal bypasses the shared path management and cache (in memory and IndexedDB) and the shared theming surface. Use `<mds-icon name=\"...\">` with the slug so the icon is cached and takes its color from CSS.\n\n```html\n<!-- INCORRECT -->\n<img src=\"/assets/img/svg/mi/baseline/add.svg\" alt=\"\">\n<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path d=\"...\"/></svg>\n\n<!-- CORRECT -->\n<mds-icon name=\"mi/baseline/add\"></mds-icon>\n```\n\n#### Do Not Slot `<mds-icon>` to Add an Icon to Another Component\n\n`<mds-icon>` has no slot and accepts no children. Other Magma components expose an `icon` prop that renders the SVG through the shared service with correct positioning. Slotting `<mds-icon>` into the default slot of another component is stripped or misaligned.\n\n```html\n<!-- INCORRECT -->\n<mds-button>\n <mds-icon name=\"mi/baseline/add\"></mds-icon>\n Aggiungi\n</mds-button>\n\n<!-- CORRECT -->\n<mds-button label=\"Aggiungi\" icon=\"mi/baseline/add\" variant=\"primary\" tone=\"weak\"></mds-button>\n```\n\n#### Do Not Configure the Path with a Bare Relative Value\n\n`setSvgPath` (on `IconsSetService` or the element) treats an absolute path (starting with `/`) as relative to `window.location.origin`, and accepts full URLs. A bare relative value like `assets/svg/` is *accepted* but resolved against the **current page URL** (or the `<base href>`, when the page has one) on each request, so it silently breaks on nested routes (e.g. `/users/42/`). Always pass an absolute path or a full URL. Only an empty/whitespace value, or one that is not a URL (e.g. `http://`), throws (`Svg path not recognize ...`).\n\n```javascript\n// FRAGILE - resolved relative to the current page, breaks on nested routes\nIconsSetService.setSvgPath('assets/svg/');\n\n// CORRECT - absolute path (prefixed with the origin)\nIconsSetService.setSvgPath('/assets/svg/');\n\n// CORRECT - full URL (for example a CDN)\nIconsSetService.setSvgPath('https://cdn.example.com/svg/');\n```\n\n#### Do Not Rely on `<mds-icon>` for an Accessible Label\n\n`<mds-icon>` renders its inner element with `aria-hidden=\"true\"`. An icon used as the sole indicator inside an interactive control or next to no visible text provides no accessible name by itself. The surrounding control must carry the accessible name.\n\n```html\n<!-- INCORRECT - button has no accessible name -->\n<button>\n <mds-icon name=\"mi/baseline/delete\"></mds-icon>\n</button>\n\n<!-- CORRECT - use mds-button with aria-label -->\n<mds-button\n icon=\"mi/baseline/delete\"\n aria-label=\"Elimina elemento\"\n variant=\"error\"\n tone=\"text\"\n></mds-button>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the SVG\n\nThe only supported styling surface is `::part(svg)` and the inherited CSS `fill` set on the host. Using `>>>`, `/deep/`, or descendant selectors on `.icon` or internal class names couples code to the Shadow DOM structure and breaks on minor releases.\n\n```css\n/* INCORRECT */\nmds-icon >>> .icon svg path {\n fill: red;\n}\nmds-icon .icon {\n transform: rotate(45deg);\n}\n\n/* CORRECT */\nmds-icon {\n fill: rgb(var(--magma-danger-fg));\n}\nmds-icon::part(svg) {\n transform: rotate(45deg);\n}\n```\n\n#### Do Not Add `.svg` Extension to a Slug\n\nThe slug passed to `name` must not include the `.svg` extension - the service appends it when building the fetch URL. Adding the extension causes a double-`.svg` path (`mi/baseline/close.svg.svg`) that returns a 404.\n\n```html\n<!-- INCORRECT -->\n<mds-icon name=\"mi/baseline/close.svg\"></mds-icon>\n\n<!-- CORRECT -->\n<mds-icon name=\"mi/baseline/close\"></mds-icon>\n```\n\n#### Do Not Override Size with Fixed `width` and `height` HTML Attributes\n\n`<mds-icon>` is a custom element - HTML `width` and `height` attributes have no effect on it. Size is controlled by the CSS `width` property on the host (height follows from `aspect-ratio: 1`). Use a Tailwind width utility or a custom CSS rule.\n\n```html\n<!-- INCORRECT - attributes are ignored -->\n<mds-icon name=\"mi/baseline/star\" width=\"32\" height=\"32\"></mds-icon>\n\n<!-- CORRECT - CSS width drives the size -->\n<mds-icon name=\"mi/baseline/star\" class=\"w-1200\"></mds-icon>\n```\n"
12798
13217
  },
12799
13218
  "props": [
@@ -13438,8 +13857,8 @@
13438
13857
  "mds-button"
13439
13858
  ],
13440
13859
  "mds-button": [
13441
- "mds-spinner",
13442
13860
  "mds-icon",
13861
+ "mds-spinner",
13443
13862
  "mds-text"
13444
13863
  ],
13445
13864
  "mds-avatar": [
@@ -13461,6 +13880,10 @@
13461
13880
  "readme": "# mds-input\n\n\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
13462
13881
  "docs": "This is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.",
13463
13882
  "docsTags": [
13883
+ {
13884
+ "name": "part",
13885
+ "text": "color-picker-button - Selects the button that opens the colour picker of a `color` field"
13886
+ },
13464
13887
  {
13465
13888
  "name": "part",
13466
13889
  "text": "counter-button-decrease - Selects the button used to decrease the input value"
@@ -13507,9 +13930,9 @@
13507
13930
  }
13508
13931
  ],
13509
13932
  "usage": {
13510
- "1. Description": "The `<mds-input>` web component is the primary single- and multi-line text entry control of the Magma Design System. It wraps a native `<input>` (or `<textarea>` when `type=\"textarea\"`) and layers on form association, validation, inline tips, iconography, password masking, numeric steppers, datalist suggestions and speech-to-text dictation.\n\n#### Semantic Behavior\n\n- **Form association**: The component reports its value to the surrounding `<form>`, so it submits natively. On `disabled` the reported value is cleared. A form reset brings back the value the field had at load, both shown and submitted, and drops the `'success'` or `'error'` look of a past blur, like a native input.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **Form validity**: The validators below also decide the validity reported to the form, on every change of the value or of the rules: like a native control, an invalid field matches `:invalid` and stops the submit, the browser shows a message in the page language next to the field and focuses it, and the field switches to `'error'` as on blur. Disabled and read-only fields are left out, and `novalidate` on the `<form>` turns the check off. `type=\"email\"` and `type=\"url\"` check the format of the value as a native input does.\n- **Validation on blur**: Validation runs when the field loses focus (and re-runs on input once invalid). A `required` field waits for that first blur too: until then, typing only updates its required tip. It drives the `variant` automatically to `'success'` or `'error'`, emits `mdsInputValidation` with the boolean result, and reverts to `'primary'` when an optional field is emptied.\n- **Type-aware validators**: The active validator set is derived from `type` - `email` and `url` install the format validators of the native types, `cf` the codice fiscale format and length validators, `isbn` a checksum validator, `piva` the partita IVA one (11 digits, the last one the check digit) and `cc` the card number one (13 to 19 digits, in groups split by spaces or dashes, that pass the Luhn check); no type applies an input mask, while `required`, `min`/`max` (any number, `0` included), `minlength`/`maxlength` and `pattern` add the corresponding constraint validators. As on a native input, `pattern` has to match the whole value, an expression that does not compile sets no rule, and `number`, `date`, `time` and `textarea` ignore it. The set is rebuilt whenever one of these props changes, also after load, as with the React wrappers under SSR: a pristine field only updates its required tip, a field already validated on blur is validated again. Custom validators can be attached at runtime through the `addValidator`/`removeValidator`/`hasValidator`/`getErrors` methods.\n- **Localized messages**: The messages of the built-in validators, the ones `getErrors()` returns and `mds-input-field` shows, are in the language of the page when the value is validated (`el`, `en`, `es`, `it`, English for any other).\n- **Error keys**: `getErrors()` reports each failed rule under its own key: `required`, `max`, `min`, `maxlength`, `minlength`, `pattern`, `email`, `url`, `piva`, `cc`, `isbn-error`, `cf-regex` and `cf-length`, plus the keys the custom validators return. Up to 2.5.0, `maxlength` and `minlength` were both reported as `minLenght`.\n- **Disabled / read-only tips**: `disabled` and `readonly` surface a persistent top tip describing the state; read-only fields also auto-select their text on focus.\n- **Character counter**: When `maxlength` is set a bottom counter tip shows `current / max` and shifts through fullness variants as the value approaches the limit. A `maxlength` of `0` or less is treated as unset.\n- **Password masking**: With `type=\"password\"` a toggle button reveals/hides the value; it is disabled with the field.\n- **Number steppers**: With `type=\"number\"` increment/decrement buttons are rendered; their placement follows `controlsLayout` and their glyphs follow `controlsIcon`. They are disabled on a disabled or read-only field, like the spin buttons of a native one.\n- **A fill a step off its surface**: on a page the field paints `surface-overlay`; inside a surface that paints `overlay` (the window of a dialog, `mds-banner`, `mds-status-bar`, `mds-dropdown`, `mds-table`) it paints `surface-default`, the step below, passed down as `--magma-field-fill`, so the field never melts into the window. `--mds-input-background` still sets the fill outright.\n- **Speech-to-text**: When `mic` is set a dictation button transcribes speech into the value, replacing what was there, and emits `mdsInputSpeechEnd` when the user stops the dictation; when the Web Speech API is unavailable the button switches to an error state and the value is left as it is. The dictation button is disabled on a disabled or read-only field, which the user cannot change, and a dictation in progress stops, emitting `mdsInputSpeechEnd`, when the field becomes so.\n- **Emitted events**: `mdsInputChange` carries the new value, `mdsInputKeydown` fires on every key pressed in the field with the native `KeyboardEvent` as detail (before the value changes: read the value from `mdsInputChange`), and `mdsInputFocus`/`mdsInputBlur` fire on focus transitions.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` ladder (color role) is defined in [`agents/variants.md`](../../../../agents/variants.md); `<mds-input>` consumes it for both intent styling and validation feedback, but does not expose a `tone` prop. It accepts `primary` (default), `ai`, `info`, `success`, `warning` and `error`.\n\n- **`type`** selects both the rendered control and the validation profile: it covers the native HTML types plus format types (`'cf'`, `'piva'`, `'isbn'`, `'cc'`) and switches the host to a multi-line `<textarea>` for `'textarea'`.\n- **`variant=\"ai\"`** auto-assigns the AI chatbot icon when no `icon` is otherwise provided, signposting AI-assisted fields.\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner icon, stepper buttons and password and microphone toggles scale with it. A `textarea` keeps its own height (`--mds-input-textarea-min-height`).\n\n#### Other behavioral props\n\n- **`icon`** is an SVG filename slug from the Magma icon library shown at the leading (left) edge of the field; it is suppressed while `await` is active, since the spinner takes its place.\n- **`controlsLayout`** chooses between stacked (`'vertical'`) and split (`'horizontal'`) stepper buttons, and **`controlsIcon`** picks arrow vs. plus/minus glyphs - both apply only to `type=\"number\"`.\n- **`datalist`** supplies suggestion options for `type=\"search\"` style autocompletion.\n- **`tip`** renders inline helper text below the field, and **`typography`** selects the field's text scale.\n",
13511
- "2. Examples": "Correct and idiomatic ways to use the `<mds-input>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Text Input\n\nThe simplest form: set `name` for form participation and `placeholder` for a visual hint. Wrap the component in [`mds-input-field`](../mds-input-field/AGENTS.md) to add a visible label and associated tip.\n\n```html\n<mds-input\n name=\"cognome\"\n placeholder=\"Inserisci il tuo cognome\"\n></mds-input>\n```\n\n#### Required Field with `tip` Helper Text\n\nUse `required` to validate that the field is not empty and `tip` to explain the constraint. The component surfaces a top-tip when focused and drives `variant` to `'error'` or `'success'` on blur. When the field collects the user's own data, set the matching `autocomplete` token (`email`, `given-name`, `tel`, ...) so browsers can identify its purpose (WCAG 2.1 SC 1.3.5) and offer autofill; without it the component default `autocomplete=\"off\"` applies.\n\n```html\n<mds-input\n name=\"email\"\n type=\"email\"\n autocomplete=\"email\"\n placeholder=\"nome@esempio.it\"\n required\n tip=\"Inserisci un indirizzo email valido\"\n></mds-input>\n```\n\n#### Textarea for Multi-line Content\n\nSet `type=\"textarea\"` to render a `<textarea>` instead of a single-line `<input>`. Use the `--mds-input-textarea-*` custom properties to control height and resize behaviour.\n\n```html\n<mds-input\n name=\"descrizione\"\n type=\"textarea\"\n placeholder=\"Descrivi il problema...\"\n maxlength=\"500\"\n></mds-input>\n```\n\n#### Character Counter via `maxlength`\n\nWhen `maxlength` is set the component renders a live `current / max` counter below the field. The counter shifts through fullness variants as the limit approaches. A value of `0` or less is treated as unset.\n\n```html\n<mds-input\n name=\"titolo\"\n placeholder=\"Titolo dell'articolo\"\n maxlength=\"120\"\n></mds-input>\n```\n\n#### Numeric Input with Steppers\n\nSet `type=\"number\"` to enable built-in increment/decrement buttons. Use `controlsLayout` to choose between stacked (`'vertical'`, default) and split (`'horizontal'`) placement, and `controlsIcon` to pick arrow vs. plus/minus glyphs. Use `min`, `max`, and `step` to constrain the legal range.\n\n```html\n<!-- Stacked (default) - arrow glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"1\"\n max=\"99\"\n step=\"1\"\n placeholder=\"1\"\n></mds-input>\n\n<!-- Horizontal split - arithmetic glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"0\"\n max=\"100\"\n controls-layout=\"horizontal\"\n controls-icon=\"arithmetic\"\n placeholder=\"0\"\n></mds-input>\n```\n\n#### Password Input\n\nSet `type=\"password\"` to render a masked field with a built-in visibility toggle. The component renders a custom dot-mask overlay and a show/hide button - no extra wiring is needed. Always set `autocomplete` to `new-password` (sign-up, password change) or `current-password` (login): the component default is `autocomplete=\"off\"`, which browsers and password managers ignore on credential fields, but the explicit token is what lets them pair the password with its username field and fill or generate the right value.\n\n```html\n<mds-input\n name=\"password\"\n type=\"password\"\n autocomplete=\"new-password\"\n placeholder=\"Scegli una password\"\n required\n></mds-input>\n```\n\n#### Login Form\n\nPair a username field carrying `autocomplete=\"username\"` with a password field carrying `autocomplete=\"current-password\"` inside a `<form>`, and submit through `<mds-button type=\"submit\">`. The native fields live in the Shadow DOM of each `<mds-input>`: among the password managers tested, Bitwarden, LastPass, Chrome and Edge detect and fill them, Firefox's built-in manager and KeePassXC-Browser do not (they only look at the light DOM).\n\n```html\n<form action=\"/login\" method=\"post\">\n <mds-input-field label=\"Email\">\n <mds-input name=\"username\" type=\"email\" autocomplete=\"username\" required></mds-input>\n </mds-input-field>\n <mds-input-field label=\"Password\">\n <mds-input name=\"password\" type=\"password\" autocomplete=\"current-password\" required></mds-input>\n </mds-input-field>\n\n <mds-button type=\"submit\" label=\"Accedi\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Italian-Specific Masked Types\n\n`type=\"cf\"` installs the codice fiscale format and length validators and `type=\"isbn\"` a checksum validator. `type=\"piva\"` accepts 11 digits whose last one is the check digit, without the `IT` prefix or spaces, and `type=\"cc\"` 13 to 19 digits, in groups split by spaces or dashes, that pass the Luhn check of card numbers. A value that breaks the format stops the submit of the form. No type applies a keyboard mask.\n\n```html\n<mds-input name=\"codice_fiscale\" type=\"cf\" placeholder=\"RSSMRA80A01H501Z\"></mds-input>\n<mds-input name=\"partita_iva\" type=\"piva\" placeholder=\"01234567890\"></mds-input>\n```\n\n#### Search Input with Datalist\n\nUse `type=\"search\"` combined with the `datalist` prop to offer autocomplete suggestions from a fixed list. The list is rendered inside the shadow DOM and wired automatically.\n\n```html\n<mds-input\n name=\"comune\"\n type=\"search\"\n placeholder=\"Cerca comune...\"\n></mds-input>\n```\n\n```javascript\n// Pass suggestions as a JavaScript array\ndocument.querySelector('mds-input').datalist = ['Roma', 'Milano', 'Napoli', 'Torino'];\n```\n\n#### Icon Decoration\n\nThe `icon` prop renders an SVG slug from the Magma icon library at the leading edge of the field. The icon is suppressed while `await` is active and the spinner takes its place.\n\n```html\n<mds-input\n name=\"cerca\"\n type=\"search\"\n icon=\"mi/baseline/search\"\n placeholder=\"Cerca...\"\n></mds-input>\n```\n\n#### AI-Assisted Field\n\nSet `variant=\"ai\"` to signal an AI-powered field. When no `icon` prop is present, the component auto-assigns the AI chatbot icon.\n\n```html\n<mds-input\n name=\"prompt\"\n type=\"text\"\n variant=\"ai\"\n placeholder=\"Chiedi qualcosa all'assistente...\"\n></mds-input>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while an async operation (e.g. a lookup) is in flight. The component renders an inline spinner in place of the icon. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-input name=\"codice\" placeholder=\"Verifica in corso...\" await></mds-input>\n```\n\n#### Speech-to-Text Dictation\n\nSet the `mic` boolean attribute to render a dictation button. Starting a dictation clears the current value and writes the recognized speech in its place; the component emits `mdsInputSpeechEnd` when the user stops the dictation. If the Web Speech API is unavailable the button switches to an error state and the value is kept.\n\n```html\n<mds-input\n name=\"note_vocali\"\n type=\"text\"\n mic\n placeholder=\"Parla o scrivi...\"\n></mds-input>\n```\n\n#### Listening to Events\n\nListen for `mdsInputChange` instead of native `input` or `change`: `change` does not cross the shadow boundary, and `input` reports only typing, not the values set by the steppers, the dictation or a script.\n\n```javascript\ndocument.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {\n console.log(e.detail.value);\n});\n\ndocument.querySelector('mds-input').addEventListener('mdsInputValidation', (e) => {\n console.log('valido:', e.detail);\n});\n```\n\n#### Form Participation\n\n`<mds-input>` is form-associated. It submits natively inside a `<form>`; set `name` so the value is included in form data. Its validation is reported to the form too: an empty `required` field, or one that breaks another rule, stops the submit like a native input and shows the error. Add `novalidate` to the `<form>` when your own code validates on submit. A reset brings every field back to its value at load and to its pristine look.\n\n```html\n<form action=\"/salva\" method=\"post\">\n <mds-input name=\"nome\" type=\"text\" placeholder=\"Nome\" required></mds-input>\n <mds-input name=\"cognome\" type=\"text\" placeholder=\"Cognome\" required></mds-input>\n <mds-input name=\"email\" type=\"email\" placeholder=\"Email\" required></mds-input>\n\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n</form>\n```\n\n#### Read-Only Display\n\nUse `readonly` when the value should be visible but not editable. A persistent top tip describes the state, and the field text is auto-selected on focus for easy copying.\n\n```html\n<mds-input\n name=\"codice_riferimento\"\n value=\"REF-2024-00123\"\n readonly\n></mds-input>\n```\n\n#### Styling Customization\n\nStyle the input only through its public `--mds-input-*` CSS custom properties. Set them on the host or a parent selector. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.search-bar mds-input {\n --mds-input-background: rgb(var(--magma-wash-base));\n}\n\n/* Textarea: fixed height, allow resize */\n.notes-area mds-input {\n --mds-input-textarea-min-height: 8rem;\n --mds-input-textarea-max-height: 24rem;\n --mds-input-textarea-resize: vertical;\n}\n```\n\n#### Sizing a Field to the Controls Next to It\n\nGive the fields of a row the `size` of the buttons beside them, so they share one height: `sm` 28px, `md` 36px, `lg` 48px (default), the sizes of [`<mds-button>`](../mds-button/AGENTS.md). `<mds-input-select>`, `<mds-input-date>` and `<mds-input-date-range>` take the same values.\n\n```html\n<div class=\"flex items-center gap-200\">\n <mds-input size=\"md\" type=\"search\" icon=\"mi/baseline/search\" placeholder=\"Cerca\"></mds-input>\n <mds-input-select size=\"md\" placeholder=\"Stato\">\n <option value=\"open\">Aperte</option>\n <option value=\"closed\">Chiuse</option>\n </mds-input-select>\n <mds-button size=\"md\" label=\"Filtra\"></mds-button>\n</div>\n```\n\n",
13512
- "3. Mistakes": "Common incorrect uses of `<mds-input>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Raw `<input>` When `<mds-input>` Exists\n\nReaching for a plain `<input>` bypasses theming, validation, tips, accessible state announcements, and form-reset behavior provided by the component.\n\n```html\n<!-- INCORRECT -->\n<input type=\"text\" name=\"nome\" placeholder=\"Nome\" class=\"my-input\">\n\n<!-- CORRECT -->\n<mds-input name=\"nome\" type=\"text\" placeholder=\"Nome\"></mds-input>\n```\n\n#### Do Not Set Boolean Attributes to the String `\"false\"`\n\n`disabled`, `required`, `readonly`, `mic` and `await` are boolean attributes: remove the attribute entirely to turn it off. `mds-input` is form-associated, so as on a native control any value turns them on, `\"false\"` included: this markup renders a disabled, required field.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"note\" disabled=\"false\" required=\"false\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input name=\"note\"></mds-input>\n```\n\n#### Do Not Force `variant` for Validation Feedback\n\nThe component drives `variant` to `'success'` or `'error'` automatically on blur when validators are active. Setting `variant` manually overrides the feedback and breaks the visual contract.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"codice\" variant=\"error\" tip=\"Valore non valido\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input name=\"codice\" required tip=\"Inserisci un valore valido\"></mds-input>\n```\n\n#### Do Not Listen to Native `input` or `change` Events\n\nThe native `change` event does not cross the shadow boundary, and `input` reports only typing, not the values set by the steppers, the dictation or a script. Use the documented `mdsInputChange` event instead, which fires for every value change.\n\n```javascript\n// INCORRECT\ndocument.querySelector('mds-input').addEventListener('input', (e) => {\n console.log(e.target.value);\n});\n\n// CORRECT\ndocument.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {\n console.log(e.detail.value);\n});\n```\n\n#### Do Not Use `type=\"number\"` Native Browser Spinners and Then Override the Input\n\nThe component renders its own increment/decrement buttons and hides the native browser spinners. Do not try to re-enable them via CSS, and do not add inline JS `stepUp`/`stepDown` calls - use the `controlsLayout` and `controlsIcon` props to configure the built-in controls.\n\n```html\n<!-- INCORRECT -->\n<mds-input type=\"number\" style=\"-moz-appearance: auto;\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input\n type=\"number\"\n controls-layout=\"horizontal\"\n controls-icon=\"arithmetic\"\n min=\"0\"\n max=\"100\"\n></mds-input>\n```\n\n#### Do Not Use a Legacy or Invalid `type` Value\n\n`<mds-input>` accepts a specific set of `type` values: `text`, `email`, `number`, `password`, `search`, `tel`, `url`, `date`, `time`, `textarea`, `cf`, `piva`, `cc`, `isbn`. Supplying anything else (e.g. `\"checkbox\"`, `\"radio\"`, `\"file\"`) is passed straight to the inner native `<input>`, which renders a bare native control that the component neither styles nor reports correctly to the form. Use the dedicated Magma component for those controls.\n\n```html\n<!-- INCORRECT -->\n<mds-input type=\"checkbox\" name=\"accetto\"></mds-input>\n<mds-input type=\"file\" name=\"allegato\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input-switch name=\"accetto\"></mds-input-switch>\n<mds-input-upload name=\"allegato\"></mds-input-upload>\n```\n\n#### Do Not Use `placeholder` as the Accessible Label\n\n`placeholder` disappears on input and is never read as a label by assistive tech. Always pair `<mds-input>` with [`mds-input-field`](../mds-input-field/AGENTS.md) (which shows a visible label and passes it down as the accessible name) or supply `aria-label` directly on the host.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"ricerca\" placeholder=\"Cerca per nome\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input-field label=\"Cerca per nome\">\n <mds-input name=\"ricerca\" placeholder=\"Cerca per nome\"></mds-input>\n</mds-input-field>\n```\n\n#### Do Not Pierce the Shadow DOM to Style Internal Parts\n\nThe supported customization surface is the public `--mds-input-*` CSS custom properties plus the documented shadow parts (`field`, `tip-top`, `tip-bottom`, `tip-count`, `password-toggle-button`, `counter-button-increase`, `counter-button-decrease`, `mic-toggle-button`). Targeting undocumented internals via `>>>` or arbitrary class names couples your code to the Shadow DOM implementation.\n\n```css\n/* INCORRECT */\nmds-input >>> .input {\n border: 2px solid red;\n}\n\n/* CORRECT */\nmds-input {\n --mds-input-ring: 0 0 0 2px rgb(var(--magma-danger-border));\n --mds-input-background: rgb(var(--magma-danger-wash-base));\n}\nmds-input::part(field) {\n font-style: italic;\n}\n```\n"
13933
+ "1. Description": "The `<mds-input>` web component is the primary single- and multi-line text entry control of the Magma Design System. It wraps a native `<input>` (or `<textarea>` when `type=\"textarea\"`) and layers on form association, validation, inline tips, iconography, password masking, numeric steppers, colour codes with a swatch and the picker of the platform, datalist suggestions and speech-to-text dictation.\n\n#### Semantic Behavior\n\n- **Form association**: The component reports its value to the surrounding `<form>`, so it submits natively. On `disabled` the reported value is cleared. A form reset brings back the value the field had at load, both shown and submitted, and drops the `'success'` or `'error'` look of a past blur, like a native input.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **Form validity**: The validators below also decide the validity reported to the form, on every change of the value or of the rules: like a native control, an invalid field matches `:invalid` and stops the submit, the browser shows a message in the page language next to the field and focuses it, and the field switches to `'error'` as on blur. Disabled and read-only fields are left out, and `novalidate` on the `<form>` turns the check off. `type=\"email\"` and `type=\"url\"` check the format of the value as a native input does.\n- **Validation on blur**: Validation runs when the field loses focus (and re-runs on input once invalid). A `required` field waits for that first blur too: until then, typing only updates its required tip. It drives the `variant` automatically to `'success'` or `'error'`, emits `mdsInputValidation` with the boolean result, and reverts to `'primary'` when an optional field is emptied.\n- **Type-aware validators**: The active validator set is derived from `type` - `email` and `url` install the format validators of the native types, `cf` the codice fiscale format and length validators, `isbn` a checksum validator, `piva` the partita IVA one (11 digits, the last one the check digit) and `cc` the card number one (13 to 19 digits, in groups split by spaces or dashes, that pass the Luhn check) and `color` the colour code one (see Colour field); no type applies an input mask, while `required`, `min`/`max` (any number, `0` included), `minlength`/`maxlength` and `pattern` add the corresponding constraint validators. As on a native input, `pattern` has to match the whole value, an expression that does not compile sets no rule, and `number`, `date`, `time`, `textarea` and `color` ignore it. The set is rebuilt whenever one of these props changes, also after load, as with the React wrappers under SSR: a pristine field only updates its required tip, a field already validated on blur is validated again. Custom validators can be attached at runtime through the `addValidator`/`removeValidator`/`hasValidator`/`getErrors` methods.\n- **Localized messages**: The messages of the built-in validators, the ones `getErrors()` returns and `mds-input-field` shows, are in the language of the page when the value is validated (`el`, `en`, `es`, `it`, English for any other).\n- **Error keys**: `getErrors()` reports each failed rule under its own key: `required`, `max`, `min`, `maxlength`, `minlength`, `pattern`, `email`, `url`, `piva`, `cc`, `color`, `isbn-error`, `cf-regex` and `cf-length`, plus the keys the custom validators return. Up to 2.5.0, `maxlength` and `minlength` were both reported as `minLenght`.\n- **Disabled / read-only tips**: `disabled` and `readonly` surface a persistent top tip describing the state; read-only fields also auto-select their text on focus. The top tip (this badge, and the dot of `required`) stands on the top border of the field, half outside, clear of its rounded corner by its radius plus a margin, and stays there while the field has the focus: inside the field it covered the button at its end.\n- **No action that changes the value on a field the user cannot change**: a read-only or disabled field (a disabled `<fieldset>` included) has none of the buttons at its end that change the value (the steppers of a number, the dictation button, the picker of a colour); its text takes their room and its end is left to the badge of its state. The password toggle stays, since it shows the value without changing it (disabled with the field).\n- **Character counter**: When `maxlength` is set a bottom counter tip shows `current / max` and shifts through fullness variants as the value approaches the limit. A `maxlength` of `0` or less is treated as unset.\n- **Password masking**: With `type=\"password\"` a toggle button reveals/hides the value; it is disabled with the field.\n- **Colour field**: `type=\"color\"` keeps a text field, where a colour code is typed and validated, with a swatch of the colour at its start and a button at its end that opens the colour picker of the platform; it keeps the sizes, the variants, `readonly`, `required`, the form and the validation, and the label and message of `mds-input-field`. The value, in `mdsInputChange` and in the form, is the colour as `#rrggbb` in lower case, the valid lowercase simple colour of HTML, without alpha. The text also takes `#rgb` and the code without `#`, in upper or lower case (what Figma copies), and the field writes it back as `#rrggbb` when it is left. Any other text, a name or `rgb()` among them, is an error under the key `color` whose message says what to write: the text stays for the user to correct and the value becomes `''`, as a native number input does with a text that is no number (the form gets `''` and the field reports `badInput`), so the event and the form only ever carry a colour or `''`. A value set by code is read the same way: `#ABC` becomes `#aabbcc`, `red` is shown with its error and the value becomes `''`. A field that is not `required` can stay empty, where a native colour input always holds `#000000`.\n- **The swatch and the picker button**: the swatch is a disc of the colour of the value, as large as the glyph of an icon and where the icon goes, so it scales with `size`; while the text names no colour it is empty, its ring alone. The ring is the `border-strong` role, the 3:1 contrast a graphic needs on the fill of the field to show a white or a black colour. The button at the end, where the microphone of a text field goes, has a palette icon and the name \"Choose a colour for\" the name of the field in the page language, and comes after the text in the order of the keyboard: it opens the colour picker of the platform (a native `<input type=\"color\">` hidden under it) on the colour of the value, black for an empty field; the colour picked writes the text and the value and emits `mdsInputChange` as typing does. A click on the swatch opens it too, a shortcut for the pointer: the swatch is hidden from assistive technologies and out of the order of the keyboard, the button is the control. A read-only or disabled field (a disabled `<fieldset>` included) has no button: it offers no way to change the value, the swatch still shows the colour and opens nothing, and the end of the field is left to the badge of its state. Next to the other props: the swatch takes the place of `icon`, which a colour field ignores (one mark at the start, as on `mds-chip`), with the icon `variant=\"ai\"` adds; `await` leaves the swatch, which shows the value, and puts its spinner at the end, before the button (at the very end of a read-only or disabled field); `mic` is ignored, since a colour code is typed or picked, not dictated, and the end holds the button.\n- **Number steppers**: With `type=\"number\"` increment/decrement buttons are rendered; their placement follows `controlsLayout` and their glyphs follow `controlsIcon`. The side buttons of the horizontal layout are as tall as the field, with the icon of an `sm` button at `md` and `sm`, as the other buttons inside the field. A read-only or disabled number has no steppers: it is a plain field, with the padding of any field and its text at the start (the centring of the horizontal layout belongs to the buttons on its sides). The arrow keys still step the value of a field the user can change.\n- **A fill a step off its surface**: on a page the field paints `surface-overlay`; inside a surface that paints `overlay` (the window of a dialog, `mds-banner`, `mds-status-bar`, `mds-dropdown`, `mds-table`) it paints `surface-default`, the step below, passed down as `--magma-field-fill`, so the field never melts into the window. `--mds-input-background` still sets the fill outright.\n- **Speech-to-text**: When `mic` is set a dictation button transcribes speech into the value, replacing what was there, and emits `mdsInputSpeechEnd` when the user stops the dictation; when the Web Speech API is unavailable the button switches to an error state and the value is left as it is. A disabled or read-only field (a disabled `<fieldset>` included), which the user cannot change, has no dictation button, and leaves the end of the field to the badge of its state; a dictation in progress stops at once, emitting `mdsInputSpeechEnd`, when the field becomes so.\n- **Emitted events**: `mdsInputChange` carries the new value, `mdsInputKeydown` fires on every key pressed in the field with the native `KeyboardEvent` as detail (before the value changes: read the value from `mdsInputChange`), and `mdsInputFocus`/`mdsInputBlur` fire on focus transitions.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` ladder (color role) is defined in [`agents/variants.md`](../../../../agents/variants.md); `<mds-input>` consumes it for both intent styling and validation feedback, but does not expose a `tone` prop. It accepts `primary` (default), `ai`, `info`, `success`, `warning` and `error`.\n\n- **`type`** selects both the rendered control and the validation profile: it covers the native HTML types (`color` as a text field with a swatch and a picker button, see Colour field) plus format types (`'cf'`, `'piva'`, `'isbn'`, `'cc'`) and switches the host to a multi-line `<textarea>` for `'textarea'`.\n- **`variant=\"ai\"`** auto-assigns the AI chatbot icon when no `icon` is otherwise provided, signposting AI-assisted fields.\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner icon, stepper buttons and password and microphone toggles scale with it. A `textarea` keeps its own height (`--mds-input-textarea-min-height`).\n\n#### Other behavioral props\n\n- **`icon`** is an SVG filename slug from the Magma icon library shown at the leading (left) edge of the field; it is suppressed while `await` is active, since the spinner takes its place. A `color` field ignores it: its swatch stands there.\n- **`controlsLayout`** chooses between stacked (`'vertical'`) and split (`'horizontal'`) stepper buttons, and **`controlsIcon`** picks arrow vs. plus/minus glyphs - both apply only to `type=\"number\"`.\n- **`datalist`** supplies suggestion options for `type=\"search\"` style autocompletion.\n- **`tip`** renders inline helper text below the field, and **`typography`** selects the field's text scale.\n",
13934
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-input>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Text Input\n\nThe simplest form: set `name` for form participation and `placeholder` for a visual hint. Wrap the component in [`mds-input-field`](../mds-input-field/AGENTS.md) to add a visible label and associated tip.\n\n```html\n<mds-input\n name=\"cognome\"\n placeholder=\"Inserisci il tuo cognome\"\n></mds-input>\n```\n\n#### Required Field with `tip` Helper Text\n\nUse `required` to validate that the field is not empty and `tip` to explain the constraint. The component surfaces a top-tip when focused and drives `variant` to `'error'` or `'success'` on blur. When the field collects the user's own data, set the matching `autocomplete` token (`email`, `given-name`, `tel`, ...) so browsers can identify its purpose (WCAG 2.1 SC 1.3.5) and offer autofill; without it the component default `autocomplete=\"off\"` applies.\n\n```html\n<mds-input\n name=\"email\"\n type=\"email\"\n autocomplete=\"email\"\n placeholder=\"nome@esempio.it\"\n required\n tip=\"Inserisci un indirizzo email valido\"\n></mds-input>\n```\n\n#### Textarea for Multi-line Content\n\nSet `type=\"textarea\"` to render a `<textarea>` instead of a single-line `<input>`. Use the `--mds-input-textarea-*` custom properties to control height and resize behaviour.\n\n```html\n<mds-input\n name=\"descrizione\"\n type=\"textarea\"\n placeholder=\"Descrivi il problema...\"\n maxlength=\"500\"\n></mds-input>\n```\n\n#### Character Counter via `maxlength`\n\nWhen `maxlength` is set the component renders a live `current / max` counter below the field. The counter shifts through fullness variants as the limit approaches. A value of `0` or less is treated as unset.\n\n```html\n<mds-input\n name=\"titolo\"\n placeholder=\"Titolo dell'articolo\"\n maxlength=\"120\"\n></mds-input>\n```\n\n#### Numeric Input with Steppers\n\nSet `type=\"number\"` to enable built-in increment/decrement buttons. Use `controlsLayout` to choose between stacked (`'vertical'`, default) and split (`'horizontal'`) placement, and `controlsIcon` to pick arrow vs. plus/minus glyphs. Use `min`, `max`, and `step` to constrain the legal range. A `readonly` or `disabled` number shows no steppers: the value cannot change there.\n\n```html\n<!-- Stacked (default) - arrow glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"1\"\n max=\"99\"\n step=\"1\"\n placeholder=\"1\"\n></mds-input>\n\n<!-- Horizontal split - arithmetic glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"0\"\n max=\"100\"\n controls-layout=\"horizontal\"\n controls-icon=\"arithmetic\"\n placeholder=\"0\"\n></mds-input>\n```\n\n#### Password Input\n\nSet `type=\"password\"` to render a masked field with a built-in visibility toggle. The component renders a custom dot-mask overlay and a show/hide button - no extra wiring is needed. Always set `autocomplete` to `new-password` (sign-up, password change) or `current-password` (login): the component default is `autocomplete=\"off\"`, which browsers and password managers ignore on credential fields, but the explicit token is what lets them pair the password with its username field and fill or generate the right value.\n\n```html\n<mds-input\n name=\"password\"\n type=\"password\"\n autocomplete=\"new-password\"\n placeholder=\"Scegli una password\"\n required\n></mds-input>\n```\n\n#### Login Form\n\nPair a username field carrying `autocomplete=\"username\"` with a password field carrying `autocomplete=\"current-password\"` inside a `<form>`, and submit through `<mds-button type=\"submit\">`. The native fields live in the Shadow DOM of each `<mds-input>`: among the password managers tested, Bitwarden, LastPass, Chrome and Edge detect and fill them, Firefox's built-in manager and KeePassXC-Browser do not (they only look at the light DOM).\n\n```html\n<form action=\"/login\" method=\"post\">\n <mds-input-field label=\"Email\">\n <mds-input name=\"username\" type=\"email\" autocomplete=\"username\" required></mds-input>\n </mds-input-field>\n <mds-input-field label=\"Password\">\n <mds-input name=\"password\" type=\"password\" autocomplete=\"current-password\" required></mds-input>\n </mds-input-field>\n\n <mds-button type=\"submit\" label=\"Accedi\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Italian-Specific Masked Types\n\n`type=\"cf\"` installs the codice fiscale format and length validators and `type=\"isbn\"` a checksum validator. `type=\"piva\"` accepts 11 digits whose last one is the check digit, without the `IT` prefix or spaces, and `type=\"cc\"` 13 to 19 digits, in groups split by spaces or dashes, that pass the Luhn check of card numbers. A value that breaks the format stops the submit of the form. No type applies a keyboard mask.\n\n```html\n<mds-input name=\"codice_fiscale\" type=\"cf\" placeholder=\"RSSMRA80A01H501Z\"></mds-input>\n<mds-input name=\"partita_iva\" type=\"piva\" placeholder=\"01234567890\"></mds-input>\n```\n\n#### Colour Field\n\nSet `type=\"color\"` to ask for a colour: the code is typed in the field, or picked with the button at its end (or a click on the swatch at its start), which opens the picker of the platform. The value is `#rrggbb` in lower case, in `mdsInputChange` and in the form; the field also takes `#rgb` and the code without `#`, in any case, and writes it as `#rrggbb` when it is left. Wrap it in `mds-input-field`: the label names the field and its picker button, the message shows the error of a text that names no colour. A field that is not `required` can stay empty.\n\n```html\n<mds-input-field label=\"Colore di base\">\n <mds-input name=\"base\" type=\"color\" value=\"#2f6fd0\" placeholder=\"#rrggbb\" required></mds-input>\n</mds-input-field>\n```\n\n```javascript\ndocument.querySelector('mds-input[type=\"color\"]').addEventListener('mdsInputChange', (e) => {\n // a colour as #rrggbb, or '' while the field is empty or its text names no colour\n if (e.detail.value) applyColour(e.detail.value);\n});\n```\n\n#### Search Input with Datalist\n\nUse `type=\"search\"` combined with the `datalist` prop to offer autocomplete suggestions from a fixed list. The list is rendered inside the shadow DOM and wired automatically.\n\n```html\n<mds-input\n name=\"comune\"\n type=\"search\"\n placeholder=\"Cerca comune...\"\n></mds-input>\n```\n\n```javascript\n// Pass suggestions as a JavaScript array\ndocument.querySelector('mds-input').datalist = ['Roma', 'Milano', 'Napoli', 'Torino'];\n```\n\n#### Icon Decoration\n\nThe `icon` prop renders an SVG slug from the Magma icon library at the leading edge of the field. The icon is suppressed while `await` is active and the spinner takes its place.\n\n```html\n<mds-input\n name=\"cerca\"\n type=\"search\"\n icon=\"mi/baseline/search\"\n placeholder=\"Cerca...\"\n></mds-input>\n```\n\n#### AI-Assisted Field\n\nSet `variant=\"ai\"` to signal an AI-powered field. When no `icon` prop is present, the component auto-assigns the AI chatbot icon.\n\n```html\n<mds-input\n name=\"prompt\"\n type=\"text\"\n variant=\"ai\"\n placeholder=\"Chiedi qualcosa all'assistente...\"\n></mds-input>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while an async operation (e.g. a lookup) is in flight. The component renders an inline spinner in place of the icon. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-input name=\"codice\" placeholder=\"Verifica in corso...\" await></mds-input>\n```\n\n#### Speech-to-Text Dictation\n\nSet the `mic` boolean attribute to render a dictation button. Starting a dictation clears the current value and writes the recognized speech in its place; the component emits `mdsInputSpeechEnd` when the user stops the dictation. If the Web Speech API is unavailable the button switches to an error state and the value is kept. A read-only or disabled field has no dictation button.\n\n```html\n<mds-input\n name=\"note_vocali\"\n type=\"text\"\n mic\n placeholder=\"Parla o scrivi...\"\n></mds-input>\n```\n\n#### Listening to Events\n\nListen for `mdsInputChange` instead of native `input` or `change`: `change` does not cross the shadow boundary, and `input` reports only typing, not the values set by the steppers, the dictation or a script.\n\n```javascript\ndocument.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {\n console.log(e.detail.value);\n});\n\ndocument.querySelector('mds-input').addEventListener('mdsInputValidation', (e) => {\n console.log('valido:', e.detail);\n});\n```\n\n#### Form Participation\n\n`<mds-input>` is form-associated. It submits natively inside a `<form>`; set `name` so the value is included in form data. Its validation is reported to the form too: an empty `required` field, or one that breaks another rule, stops the submit like a native input and shows the error. Add `novalidate` to the `<form>` when your own code validates on submit. A reset brings every field back to its value at load and to its pristine look.\n\n```html\n<form action=\"/salva\" method=\"post\">\n <mds-input name=\"nome\" type=\"text\" placeholder=\"Nome\" required></mds-input>\n <mds-input name=\"cognome\" type=\"text\" placeholder=\"Cognome\" required></mds-input>\n <mds-input name=\"email\" type=\"email\" placeholder=\"Email\" required></mds-input>\n\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n</form>\n```\n\n#### Read-Only Display\n\nUse `readonly` when the value should be visible but not editable. A persistent top tip, on the top border of the field, describes the state, and the field text is auto-selected on focus for easy copying. The buttons that change the value (steppers, dictation, colour picker) are not shown; the password toggle stays.\n\n```html\n<mds-input\n name=\"codice_riferimento\"\n value=\"REF-2024-00123\"\n readonly\n></mds-input>\n```\n\n#### Styling Customization\n\nStyle the input only through its public `--mds-input-*` CSS custom properties. Set them on the host or a parent selector. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.search-bar mds-input {\n --mds-input-background: rgb(var(--magma-wash-base));\n}\n\n/* Textarea: fixed height, allow resize */\n.notes-area mds-input {\n --mds-input-textarea-min-height: 8rem;\n --mds-input-textarea-max-height: 24rem;\n --mds-input-textarea-resize: vertical;\n}\n```\n\n#### Sizing a Field to the Controls Next to It\n\nGive the fields of a row the `size` of the buttons beside them, so they share one height: `sm` 28px, `md` 36px, `lg` 48px (default), the sizes of [`<mds-button>`](../mds-button/AGENTS.md). `<mds-input-select>`, `<mds-input-date>` and `<mds-input-date-range>` take the same values.\n\n```html\n<div class=\"flex items-center gap-200\">\n <mds-input size=\"md\" type=\"search\" icon=\"mi/baseline/search\" placeholder=\"Cerca\"></mds-input>\n <mds-input-select size=\"md\" placeholder=\"Stato\">\n <option value=\"open\">Aperte</option>\n <option value=\"closed\">Chiuse</option>\n </mds-input-select>\n <mds-button size=\"md\" label=\"Filtra\"></mds-button>\n</div>\n```\n\n",
13935
+ "3. Mistakes": "Common incorrect uses of `<mds-input>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Raw `<input>` When `<mds-input>` Exists\n\nReaching for a plain `<input>` bypasses theming, validation, tips, accessible state announcements, and form-reset behavior provided by the component.\n\n```html\n<!-- INCORRECT -->\n<input type=\"text\" name=\"nome\" placeholder=\"Nome\" class=\"my-input\">\n\n<!-- CORRECT -->\n<mds-input name=\"nome\" type=\"text\" placeholder=\"Nome\"></mds-input>\n```\n\n#### Do Not Use a Native `<input type=\"color\">` in a Form of Magma\n\nThe native colour input looks like no other field of the form, has no text to type or paste a code into, no message, no variant and no label of `mds-input-field`, and always holds a colour (`#000000`), so it cannot be left empty. `type=\"color\"` gives the field of Magma with the picker of the platform on the button at its end.\n\n```html\n<!-- INCORRECT -->\n<label>Colore di base <input type=\"color\" name=\"base\" value=\"#2f6fd0\"></label>\n\n<!-- CORRECT -->\n<mds-input-field label=\"Colore di base\">\n <mds-input type=\"color\" name=\"base\" value=\"#2f6fd0\"></mds-input>\n</mds-input-field>\n```\n\n#### Do Not Set Boolean Attributes to the String `\"false\"`\n\n`disabled`, `required`, `readonly`, `mic` and `await` are boolean attributes: remove the attribute entirely to turn it off. `mds-input` is form-associated, so as on a native control any value turns them on, `\"false\"` included: this markup renders a disabled, required field.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"note\" disabled=\"false\" required=\"false\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input name=\"note\"></mds-input>\n```\n\n#### Do Not Force `variant` for Validation Feedback\n\nThe component drives `variant` to `'success'` or `'error'` automatically on blur when validators are active. Setting `variant` manually overrides the feedback and breaks the visual contract.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"codice\" variant=\"error\" tip=\"Valore non valido\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input name=\"codice\" required tip=\"Inserisci un valore valido\"></mds-input>\n```\n\n#### Do Not Listen to Native `input` or `change` Events\n\nThe native `change` event does not cross the shadow boundary, and `input` reports only typing, not the values set by the steppers, the dictation or a script. Use the documented `mdsInputChange` event instead, which fires for every value change.\n\n```javascript\n// INCORRECT\ndocument.querySelector('mds-input').addEventListener('input', (e) => {\n console.log(e.target.value);\n});\n\n// CORRECT\ndocument.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {\n console.log(e.detail.value);\n});\n```\n\n#### Do Not Use `type=\"number\"` Native Browser Spinners and Then Override the Input\n\nThe component renders its own increment/decrement buttons and hides the native browser spinners. Do not try to re-enable them via CSS, and do not add inline JS `stepUp`/`stepDown` calls - use the `controlsLayout` and `controlsIcon` props to configure the built-in controls.\n\n```html\n<!-- INCORRECT -->\n<mds-input type=\"number\" style=\"-moz-appearance: auto;\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input\n type=\"number\"\n controls-layout=\"horizontal\"\n controls-icon=\"arithmetic\"\n min=\"0\"\n max=\"100\"\n></mds-input>\n```\n\n#### Do Not Use a Legacy or Invalid `type` Value\n\n`<mds-input>` accepts a specific set of `type` values: `text`, `email`, `number`, `password`, `search`, `tel`, `url`, `date`, `time`, `textarea`, `cf`, `piva`, `cc`, `isbn`. Supplying anything else (e.g. `\"checkbox\"`, `\"radio\"`, `\"file\"`) is passed straight to the inner native `<input>`, which renders a bare native control that the component neither styles nor reports correctly to the form. Use the dedicated Magma component for those controls.\n\n```html\n<!-- INCORRECT -->\n<mds-input type=\"checkbox\" name=\"accetto\"></mds-input>\n<mds-input type=\"file\" name=\"allegato\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input-switch name=\"accetto\"></mds-input-switch>\n<mds-input-upload name=\"allegato\"></mds-input-upload>\n```\n\n#### Do Not Use `placeholder` as the Accessible Label\n\n`placeholder` disappears on input and is never read as a label by assistive tech. Always pair `<mds-input>` with [`mds-input-field`](../mds-input-field/AGENTS.md) (which shows a visible label and passes it down as the accessible name) or supply `aria-label` directly on the host.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"ricerca\" placeholder=\"Cerca per nome\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input-field label=\"Cerca per nome\">\n <mds-input name=\"ricerca\" placeholder=\"Cerca per nome\"></mds-input>\n</mds-input-field>\n```\n\n#### Do Not Pierce the Shadow DOM to Style Internal Parts\n\nThe supported customization surface is the public `--mds-input-*` CSS custom properties plus the documented shadow parts (`field`, `tip-top`, `tip-bottom`, `tip-count`, `password-toggle-button`, `counter-button-increase`, `counter-button-decrease`, `mic-toggle-button`, `color-picker-button`). Targeting undocumented internals via `>>>` or arbitrary class names couples your code to the Shadow DOM implementation.\n\n```css\n/* INCORRECT */\nmds-input >>> .input {\n border: 2px solid red;\n}\n\n/* CORRECT */\nmds-input {\n --mds-input-ring: 0 0 0 2px rgb(var(--magma-danger-border));\n --mds-input-background: rgb(var(--magma-danger-wash-base));\n}\nmds-input::part(field) {\n font-style: italic;\n}\n```\n"
13513
13936
  },
13514
13937
  "props": [
13515
13938
  {
@@ -13834,7 +14257,7 @@
13834
14257
  "mutable": false,
13835
14258
  "attr": "await",
13836
14259
  "reflectToAttr": true,
13837
- "docs": "Specifies if the spinner icon is shown, replacing the icon if present",
14260
+ "docs": "Specifies if the spinner icon is shown, replacing the icon if present. A `color` field keeps\nits swatch, which shows the value, and shows the spinner at its end, before the picker button\n(read-only or disabled, the field has no picker button and the spinner takes the end)",
13838
14261
  "docsTags": [
13839
14262
  {
13840
14263
  "name": "default",
@@ -13870,7 +14293,7 @@
13870
14293
  "mutable": false,
13871
14294
  "attr": "controls-icon",
13872
14295
  "reflectToAttr": true,
13873
- "docs": "Specifies the icon type of the counter button when the input type is set to `number`",
14296
+ "docs": "Specifies the icon type of the counter buttons when the input type is set to `number`",
13874
14297
  "docsTags": [
13875
14298
  {
13876
14299
  "name": "default",
@@ -13914,7 +14337,7 @@
13914
14337
  "mutable": false,
13915
14338
  "attr": "controls-layout",
13916
14339
  "reflectToAttr": true,
13917
- "docs": "Specifies the layout of the counter button when the input type is set to `number`",
14340
+ "docs": "Specifies the layout of the counter buttons when the input type is set to `number`: stacked at\nthe end (`vertical`) or one at each end (`horizontal`). A read-only or disabled field has no\ncounter buttons, and its text takes the room they leave",
13918
14341
  "docsTags": [
13919
14342
  {
13920
14343
  "name": "default",
@@ -13976,7 +14399,7 @@
13976
14399
  "mutable": false,
13977
14400
  "attr": "disabled",
13978
14401
  "reflectToAttr": true,
13979
- "docs": "If true, the element is displayed as disabled",
14402
+ "docs": "If true, the element is displayed as disabled. The buttons that change the value (the counter\nbuttons of a number, the microphone, the picker of a colour) are not shown: the end of the\nfield is left to the badge of its state",
13980
14403
  "docsTags": [
13981
14404
  {
13982
14405
  "name": "default",
@@ -14008,7 +14431,7 @@
14008
14431
  "mutable": true,
14009
14432
  "attr": "icon",
14010
14433
  "reflectToAttr": true,
14011
- "docs": "An icon displayed at the left of the input, inside the field; the spinner of `await` takes\nits place",
14434
+ "docs": "An icon displayed at the left of the input, inside the field; the spinner of `await` takes\nits place. A `color` field ignores it: its swatch stands there, one mark at the start",
14012
14435
  "docsTags": [],
14013
14436
  "values": [
14014
14437
  {
@@ -14094,7 +14517,7 @@
14094
14517
  "mutable": false,
14095
14518
  "attr": "mic",
14096
14519
  "reflectToAttr": true,
14097
- "docs": "Toggles text recognition",
14520
+ "docs": "Toggles text recognition. A read-only or disabled field has no dictation button. A `color`\nfield ignores it: a colour code is typed or picked, not dictated, and its end holds the button\nof the picker",
14098
14521
  "docsTags": [],
14099
14522
  "values": [
14100
14523
  {
@@ -14263,7 +14686,7 @@
14263
14686
  "mutable": false,
14264
14687
  "attr": "readonly",
14265
14688
  "reflectToAttr": true,
14266
- "docs": "Specifies that the element is read-only",
14689
+ "docs": "Specifies that the element is read-only. The buttons that change the value (the counter\nbuttons of a number, the microphone, the picker of a colour) are not shown, as on a disabled\nfield; the password toggle stays, since it shows the value without changing it",
14267
14690
  "docsTags": [
14268
14691
  {
14269
14692
  "name": "default",
@@ -14423,10 +14846,10 @@
14423
14846
  },
14424
14847
  {
14425
14848
  "name": "type",
14426
- "type": "\"cc\" | \"cf\" | \"date\" | \"email\" | \"isbn\" | \"number\" | \"password\" | \"piva\" | \"search\" | \"tel\" | \"text\" | \"textarea\" | \"time\" | \"url\" | undefined",
14849
+ "type": "\"cc\" | \"cf\" | \"color\" | \"date\" | \"email\" | \"isbn\" | \"number\" | \"password\" | \"piva\" | \"search\" | \"tel\" | \"text\" | \"textarea\" | \"time\" | \"url\" | undefined",
14427
14850
  "complexType": {
14428
14851
  "original": "InputTextType",
14429
- "resolved": "\"cc\" | \"cf\" | \"date\" | \"email\" | \"isbn\" | \"number\" | \"password\" | \"piva\" | \"search\" | \"tel\" | \"text\" | \"textarea\" | \"time\" | \"url\" | undefined",
14852
+ "resolved": "\"cc\" | \"cf\" | \"color\" | \"date\" | \"email\" | \"isbn\" | \"number\" | \"password\" | \"piva\" | \"search\" | \"tel\" | \"text\" | \"textarea\" | \"time\" | \"url\" | undefined",
14430
14853
  "references": {
14431
14854
  "InputTextType": {
14432
14855
  "location": "import",
@@ -14439,7 +14862,7 @@
14439
14862
  "mutable": false,
14440
14863
  "attr": "type",
14441
14864
  "reflectToAttr": true,
14442
- "docs": "Specifies the type of input element",
14865
+ "docs": "Specifies the type of input element. `color` holds a colour: the field stays a text field,\nwhere the code is typed and validated, with a swatch of the colour at its start and a button\nat its end that opens the colour picker of the platform. Its value, in the change event and\nin the form, is the colour as\n`#rrggbb` in lower case, or `''` while the text is empty or names no colour, which is a\nvalidation error; the text also takes `#rgb` and the code without `#`, in any case, and is\nwritten back as `#rrggbb` when the field is left",
14443
14866
  "docsTags": [
14444
14867
  {
14445
14868
  "name": "default",
@@ -14456,6 +14879,10 @@
14456
14879
  "value": "cf",
14457
14880
  "type": "string"
14458
14881
  },
14882
+ {
14883
+ "value": "color",
14884
+ "type": "string"
14885
+ },
14459
14886
  {
14460
14887
  "value": "date",
14461
14888
  "type": "string"
@@ -14565,7 +14992,7 @@
14565
14992
  "mutable": true,
14566
14993
  "attr": "value",
14567
14994
  "reflectToAttr": true,
14568
- "docs": "Specifies the value of the input element",
14995
+ "docs": "Specifies the value of the input element. With `type=\"color\"`, a colour as `#rrggbb`: a value\nset as `#rgb`, without `#` or in upper case is written so, and one that names no colour is\nshown as it is, with its error, while the value becomes `''`",
14569
14996
  "docsTags": [
14570
14997
  {
14571
14998
  "name": "default",
@@ -15051,19 +15478,19 @@
15051
15478
  {
15052
15479
  "name": "--mds-input-tip-horizontal-offset",
15053
15480
  "annotation": "prop",
15054
- "docs": "The default horizontal offset applied to the input tip",
15481
+ "docs": "The default horizontal offset applied to the bottom tip",
15055
15482
  "visibility": "internal"
15056
15483
  },
15057
15484
  {
15058
15485
  "name": "--mds-input-tip-horizontal-offset-focused",
15059
15486
  "annotation": "prop",
15060
- "docs": "The horizontal offset applied when the input tip is focused",
15487
+ "docs": "The horizontal offset applied to the bottom tip when the input is focused",
15061
15488
  "visibility": "internal"
15062
15489
  },
15063
15490
  {
15064
15491
  "name": "--mds-input-tip-vertical-offset",
15065
15492
  "annotation": "prop",
15066
- "docs": "The vertical offset applied to the input tip",
15493
+ "docs": "The vertical offset applied to the bottom tip",
15067
15494
  "visibility": "internal"
15068
15495
  },
15069
15496
  {
@@ -15075,6 +15502,10 @@
15075
15502
  ],
15076
15503
  "slots": [],
15077
15504
  "parts": [
15505
+ {
15506
+ "name": "color-picker-button",
15507
+ "docs": "Selects the button that opens the colour picker of a `color` field"
15508
+ },
15078
15509
  {
15079
15510
  "name": "counter-button-decrease",
15080
15511
  "docs": "Selects the button used to decrease the input value"
@@ -15136,8 +15567,8 @@
15136
15567
  "mds-spinner"
15137
15568
  ],
15138
15569
  "mds-button": [
15139
- "mds-spinner",
15140
15570
  "mds-icon",
15571
+ "mds-spinner",
15141
15572
  "mds-text"
15142
15573
  ],
15143
15574
  "mds-input-tip-item": [
@@ -15166,8 +15597,8 @@
15166
15597
  }
15167
15598
  ],
15168
15599
  "usage": {
15169
- "1. Description": "The `<mds-input-date>` web component is the Magma Design System control for capturing a single calendar date. It wraps a native `<input type=\"date\">`, adding form association, ISO value validation against an optional `min`/`max` range, contextual tips, and a button-triggered calendar dropdown for visual date picking.\n\n#### Semantic Behavior\n\n- **Form association**: The host participates natively in form submission and exposes its `value` under `name`; a form reset brings back the date the field had at load, both shown and submitted, and its pristine look, like a native input. An invalid value submits nothing, and its invalid state is reported to the form: like a native control, the field matches `:invalid` and stops the submit, with a message in the page language (a missing required date, a date out of the range, an unreadable one). A disabled or read-only field is left out, and `novalidate` on the `<form>` turns the check off.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **ISO value contract**: `value`, `min`, and `max` are all ISO date strings (`YYYY-MM-DD`); other formats are not accepted.\n- **Validation on change**: The value is checked when the component loads, on every value change and whenever `required`, `min` or `max` change (also after load, as with the React wrappers under SSR). The validity reported to the form, the submitted value and the required tip follow every check: a date invalid, missing while `required` or outside the `min`/`max` range submits no value. The look follows once the field is touched, like `:user-invalid` on a native control: after the user edits or leaves the field, picks a date from the calendar, or a stopped submit points at it, each check sets `variant` to `'error'` or `'primary'` and emits `mdsInputValidation` with a boolean. An empty `required` field therefore loads in its own variant, not in `'error'`.\n- **Range self-correction**: If `max` is earlier than `min`, at load or after a later change of either, `max` is snapped to equal `min`.\n- **Selection event**: `mdsInputDateSelect` fires with the new string value whenever `value` changes, whether typed or picked from the calendar.\n- **Calendar dropdown**: The trailing calendar button, icon-only and named in the page language (the `lang` of `<html>`) (\"Open calendar\"), opens a single-date calendar; picking a day writes back the value and, after `delay`, auto-closes.\n- **Slotted mode**: When the host carries a `slot` attribute it is treated as embedded - the calendar button, dropdown, and calendar are not rendered, leaving only the bare input for composition inside a larger field.\n- **Contextual tips**: A tip surfaces `disabled`, `readonly`, and `required` states; the required tip expands on focus and reflects success once the value is valid.\n- **Read-only**: A read-only field shows its tip and auto-selects its text on focus; its native input is read-only and its calendar button disabled, so the value cannot be changed.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` ladder is defined in [`agents/variants.md`](../../../../agents/variants.md). Note that `variant` is mutable here: once the field is touched, the component overrides it to `'error'` / `'primary'` as validation dictates, so a variant set in the markup or from script lasts until the user edits or leaves the field.\n\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner calendar button scale with it.\n\n#### Other behavioral props\n\n- **`min`** / **`max`** bound the selectable range; dates outside it invalidate the field rather than being silently clamped.\n- **`delay`** is the milliseconds to wait before auto-closing the calendar dropdown after a pick; setting it to `0` keeps the dropdown open.\n- **`required`** makes an empty or invalid value fail validation and drives the required/required-success tip.\n",
15170
- "2. Examples": "Correct and idiomatic ways to use the `<mds-input-date>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant ladder documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Date Input\n\nThe simplest form. Wrap in [`mds-input-field`](../mds-input-field/AGENTS.md) to attach a visible label. Use `name` so the value is submitted with the form.\n\n```html\n<mds-input-field label=\"Data di nascita\">\n <mds-input-date name=\"birthdate\"></mds-input-date>\n</mds-input-field>\n```\n\n#### Pre-filled Value\n\nSet `value` to an ISO date string (`YYYY-MM-DD`) to initialize the picker with a known date. Do not use other date formats.\n\n```html\n<mds-input-date name=\"dataScadenza\" value=\"2026-12-31\"></mds-input-date>\n```\n\n#### Required Field\n\nAdd `required` to make an empty or invalid date fail validation. The component surfaces a tip on focus; the field stops the submit while empty, and turns to `'error'` once the user leaves it empty or a stopped submit points at it, until a valid date is entered.\n\n```html\n<mds-input-field label=\"Data di inizio *\">\n <mds-input-date name=\"startDate\" required></mds-input-date>\n</mds-input-field>\n```\n\n#### Bounded Date Range\n\nUse `min` and `max` (both ISO strings) to restrict the selectable range. Dates outside the range invalidate the field and, once it is touched, emit `mdsInputValidation` with `false`. If `max` is earlier than `min` at load time, the component snaps `max` to equal `min`.\n\n```html\n<mds-input-date\n name=\"dataSopralluogo\"\n min=\"2026-01-01\"\n max=\"2026-12-31\"\n></mds-input-date>\n```\n\n#### Listening to Value Changes\n\nListen to `mdsInputDateSelect` (fires with the new ISO string) for every value change - whether typed or picked from the calendar. Listen to `mdsInputValidation` to react to validity changes.\n\n```html\n<mds-input-date id=\"picker\" name=\"dataEvento\"></mds-input-date>\n\n<script>\n const picker = document.getElementById('picker');\n\n picker.addEventListener('mdsInputDateSelect', (e) => {\n console.log('Data selezionata:', e.detail); // \"2026-06-15\"\n });\n\n picker.addEventListener('mdsInputValidation', (e) => {\n console.log('Valido:', e.detail); // true | false\n });\n</script>\n```\n\n#### Programmatic Value via `setValue`\n\nUse the `setValue` method to set the value from JavaScript; it emits `mdsInputDateSelect` and checks the value. Unlike a user interaction it does not touch the field: on a pristine field the validity reaches the form, but the variant and `mdsInputValidation` wait for the user.\n\n```html\n<mds-input-date id=\"datePicker\" name=\"dataConsegna\"></mds-input-date>\n\n<script>\n document.getElementById('datePicker').setValue('2026-09-01');\n</script>\n```\n\n#### Controlling Calendar Auto-close Delay\n\nThe calendar dropdown closes `delay` milliseconds after a date is picked (default 500 ms). Set `delay=\"0\"` to keep it open after selection - useful when the picker is used inside a form where the user might want to confirm before the overlay disappears.\n\n```html\n<!-- Default: closes 500 ms after pick -->\n<mds-input-date name=\"dataRiunione\" delay=\"500\"></mds-input-date>\n\n<!-- Keep open until the user dismisses manually -->\n<mds-input-date name=\"dataRiunione\" delay=\"0\"></mds-input-date>\n```\n\n#### Disabled and Read-only States\n\n`disabled` blocks all interaction and removes the field from the tab sequence. `readonly` keeps the field in the tab sequence and selects its text on focus, but the date cannot be changed: the native input is read-only and the calendar button disabled. Both surface a contextual tip.\n\n```html\n<!-- Disabled: no interaction at all -->\n<mds-input-date name=\"dataArchiviazione\" disabled value=\"2025-01-01\"></mds-input-date>\n\n<!-- Read-only: focusable, not editable -->\n<mds-input-date name=\"dataCreazione\" readonly value=\"2024-06-01\"></mds-input-date>\n```\n\n#### Form Participation\n\n`<mds-input-date>` is form-associated and submits its ISO value under `name`. A missing `required` date, or one out of the `min`/`max` range, stops the submit like a native control. A form reset brings back the date of load, both shown and submitted.\n\n```html\n<form action=\"/prenota\" method=\"post\">\n <mds-input-field label=\"Data prenotazione\">\n <mds-input-date name=\"bookingDate\" required></mds-input-date>\n </mds-input-field>\n <mds-button type=\"submit\" label=\"Conferma\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Slotted Mode Inside a Compound Field\n\nWhen the host carries a `slot` attribute, the component renders only the bare native input - the calendar button, dropdown, and calendar are suppressed. This is the correct way to embed the date input inside [`mds-input-date-range`](../mds-input-date-range/AGENTS.md) or a custom compound field.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\" name=\"rangeStart\"></mds-input-date>\n <mds-input-date slot=\"end\" name=\"rangeEnd\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Variant Override for External State Signalling\n\n`variant` is driven automatically by validation (`'error'` on invalid, `'primary'` on valid) once the field is touched. To communicate an external state, write it in the markup or set it from script: it lasts until the user edits or leaves the field. Values follow the theme input ladder: `primary` (default), `error`, `success`, `warning`, `info`, `ai`.\n\n```html\n<mds-input-date id=\"dataConferma\" name=\"dataConferma\" value=\"2026-03-15\"></mds-input-date>\n\n<script>\n // Pre-mark as success when the date was already validated server-side\n const field = document.getElementById('dataConferma');\n field.componentOnReady().then(() => {\n field.variant = 'success';\n });\n</script>\n```\n\n#### Styling Customization\n\nStyle the component only through its public `--mds-input-date-*` CSS custom properties. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast work automatically.\n\n```css\n.booking-widget mds-input-date {\n --mds-input-date-background: rgb(var(--magma-wash-base));\n --mds-input-date-ring: 0 0 0 2px rgb(var(--magma-border-focus) / 0.5);\n}\n```\n",
15600
+ "1. Description": "The `<mds-input-date>` web component is the Magma Design System control for capturing a single calendar date. It wraps a native `<input type=\"date\">`, adding form association, ISO value validation against an optional `min`/`max` range, contextual tips, and a button-triggered calendar dropdown for visual date picking.\n\n#### Semantic Behavior\n\n- **Form association**: The host participates natively in form submission and exposes its `value` under `name`; a form reset brings back the date the field had at load, both shown and submitted, and its pristine look, like a native input. An invalid value submits nothing, and its invalid state is reported to the form: like a native control, the field matches `:invalid` and stops the submit, with a message in the page language (a missing required date, a date out of the range, an unreadable one). A disabled or read-only field is left out, and `novalidate` on the `<form>` turns the check off.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **ISO value contract**: `value`, `min`, and `max` are all ISO date strings (`YYYY-MM-DD`); other formats are not accepted.\n- **Validation on change**: The value is checked when the component loads, on every value change and whenever `required`, `min` or `max` change (also after load, as with the React wrappers under SSR). The validity reported to the form, the submitted value and the required tip follow every check: a date invalid, missing while `required` or outside the `min`/`max` range submits no value. The look follows once the field is touched, like `:user-invalid` on a native control: after the user edits or leaves the field, picks a date from the calendar, or a stopped submit points at it, each check sets `variant` to `'error'` or `'primary'` and emits `mdsInputValidation` with a boolean. An empty `required` field therefore loads in its own variant, not in `'error'`.\n- **Range self-correction**: If `max` is earlier than `min`, at load or after a later change of either, `max` is snapped to equal `min`.\n- **Selection event**: `mdsInputDateSelect` fires with the new string value whenever `value` changes, whether typed or picked from the calendar.\n- **Calendar dropdown**: The trailing calendar button, icon-only and named in the page language (the `lang` of `<html>`) (\"Open calendar\"), opens a single-date calendar; picking a day writes back the value and, after `delay`, auto-closes. It is shown only while the user can change the date: a read-only or disabled field (a disabled `<fieldset>` included) has no calendar button, its text takes its room and its end is left to the badge of its state; a calendar open on a field that becomes so closes.\n- **Slotted mode**: When the host carries a `slot` attribute it is treated as embedded - the calendar button, dropdown, and calendar are not rendered, leaving only the bare input for composition inside a larger field.\n- **Contextual tips**: A tip surfaces `disabled`, `readonly`, and `required` states; the required tip expands on focus and reflects success once the value is valid. It stands on the top border of the field, half outside, clear of its rounded corner, and stays there while the field has the focus, as on `mds-input`.\n- **Read-only**: A read-only field shows its tip and auto-selects its text on focus; its native input is read-only and it has no calendar button, so the value cannot be changed.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` ladder is defined in [`agents/variants.md`](../../../../agents/variants.md). Note that `variant` is mutable here: once the field is touched, the component overrides it to `'error'` / `'primary'` as validation dictates, so a variant set in the markup or from script lasts until the user edits or leaves the field.\n\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner calendar button scale with it.\n\n#### Other behavioral props\n\n- **`min`** / **`max`** bound the selectable range; dates outside it invalidate the field rather than being silently clamped.\n- **`delay`** is the milliseconds to wait before auto-closing the calendar dropdown after a pick; setting it to `0` keeps the dropdown open.\n- **`required`** makes an empty or invalid value fail validation and drives the required/required-success tip.\n",
15601
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-input-date>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant ladder documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Date Input\n\nThe simplest form. Wrap in [`mds-input-field`](../mds-input-field/AGENTS.md) to attach a visible label. Use `name` so the value is submitted with the form.\n\n```html\n<mds-input-field label=\"Data di nascita\">\n <mds-input-date name=\"birthdate\"></mds-input-date>\n</mds-input-field>\n```\n\n#### Pre-filled Value\n\nSet `value` to an ISO date string (`YYYY-MM-DD`) to initialize the picker with a known date. Do not use other date formats.\n\n```html\n<mds-input-date name=\"dataScadenza\" value=\"2026-12-31\"></mds-input-date>\n```\n\n#### Required Field\n\nAdd `required` to make an empty or invalid date fail validation. The component surfaces a tip on focus; the field stops the submit while empty, and turns to `'error'` once the user leaves it empty or a stopped submit points at it, until a valid date is entered.\n\n```html\n<mds-input-field label=\"Data di inizio *\">\n <mds-input-date name=\"startDate\" required></mds-input-date>\n</mds-input-field>\n```\n\n#### Bounded Date Range\n\nUse `min` and `max` (both ISO strings) to restrict the selectable range. Dates outside the range invalidate the field and, once it is touched, emit `mdsInputValidation` with `false`. If `max` is earlier than `min` at load time, the component snaps `max` to equal `min`.\n\n```html\n<mds-input-date\n name=\"dataSopralluogo\"\n min=\"2026-01-01\"\n max=\"2026-12-31\"\n></mds-input-date>\n```\n\n#### Listening to Value Changes\n\nListen to `mdsInputDateSelect` (fires with the new ISO string) for every value change - whether typed or picked from the calendar. Listen to `mdsInputValidation` to react to validity changes.\n\n```html\n<mds-input-date id=\"picker\" name=\"dataEvento\"></mds-input-date>\n\n<script>\n const picker = document.getElementById('picker');\n\n picker.addEventListener('mdsInputDateSelect', (e) => {\n console.log('Data selezionata:', e.detail); // \"2026-06-15\"\n });\n\n picker.addEventListener('mdsInputValidation', (e) => {\n console.log('Valido:', e.detail); // true | false\n });\n</script>\n```\n\n#### Programmatic Value via `setValue`\n\nUse the `setValue` method to set the value from JavaScript; it emits `mdsInputDateSelect` and checks the value. Unlike a user interaction it does not touch the field: on a pristine field the validity reaches the form, but the variant and `mdsInputValidation` wait for the user.\n\n```html\n<mds-input-date id=\"datePicker\" name=\"dataConsegna\"></mds-input-date>\n\n<script>\n document.getElementById('datePicker').setValue('2026-09-01');\n</script>\n```\n\n#### Controlling Calendar Auto-close Delay\n\nThe calendar dropdown closes `delay` milliseconds after a date is picked (default 500 ms). Set `delay=\"0\"` to keep it open after selection - useful when the picker is used inside a form where the user might want to confirm before the overlay disappears.\n\n```html\n<!-- Default: closes 500 ms after pick -->\n<mds-input-date name=\"dataRiunione\" delay=\"500\"></mds-input-date>\n\n<!-- Keep open until the user dismisses manually -->\n<mds-input-date name=\"dataRiunione\" delay=\"0\"></mds-input-date>\n```\n\n#### Disabled and Read-only States\n\n`disabled` blocks all interaction and removes the field from the tab sequence. `readonly` keeps the field in the tab sequence and selects its text on focus, but the date cannot be changed: the native input is read-only and there is no calendar button. Both surface a contextual tip on the top border, and leave the end of the field to it.\n\n```html\n<!-- Disabled: no interaction at all -->\n<mds-input-date name=\"dataArchiviazione\" disabled value=\"2025-01-01\"></mds-input-date>\n\n<!-- Read-only: focusable, not editable -->\n<mds-input-date name=\"dataCreazione\" readonly value=\"2024-06-01\"></mds-input-date>\n```\n\n#### Form Participation\n\n`<mds-input-date>` is form-associated and submits its ISO value under `name`. A missing `required` date, or one out of the `min`/`max` range, stops the submit like a native control. A form reset brings back the date of load, both shown and submitted.\n\n```html\n<form action=\"/prenota\" method=\"post\">\n <mds-input-field label=\"Data prenotazione\">\n <mds-input-date name=\"bookingDate\" required></mds-input-date>\n </mds-input-field>\n <mds-button type=\"submit\" label=\"Conferma\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Slotted Mode Inside a Compound Field\n\nWhen the host carries a `slot` attribute, the component renders only the bare native input - the calendar button, dropdown, and calendar are suppressed. This is the correct way to embed the date input inside [`mds-input-date-range`](../mds-input-date-range/AGENTS.md) or a custom compound field.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\" name=\"rangeStart\"></mds-input-date>\n <mds-input-date slot=\"end\" name=\"rangeEnd\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Variant Override for External State Signalling\n\n`variant` is driven automatically by validation (`'error'` on invalid, `'primary'` on valid) once the field is touched. To communicate an external state, write it in the markup or set it from script: it lasts until the user edits or leaves the field. Values follow the theme input ladder: `primary` (default), `error`, `success`, `warning`, `info`, `ai`.\n\n```html\n<mds-input-date id=\"dataConferma\" name=\"dataConferma\" value=\"2026-03-15\"></mds-input-date>\n\n<script>\n // Pre-mark as success when the date was already validated server-side\n const field = document.getElementById('dataConferma');\n field.componentOnReady().then(() => {\n field.variant = 'success';\n });\n</script>\n```\n\n#### Styling Customization\n\nStyle the component only through its public `--mds-input-date-*` CSS custom properties. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast work automatically.\n\n```css\n.booking-widget mds-input-date {\n --mds-input-date-background: rgb(var(--magma-wash-base));\n --mds-input-date-ring: 0 0 0 2px rgb(var(--magma-border-focus) / 0.5);\n}\n```\n",
15171
15602
  "3. Mistakes": "Common incorrect uses of `<mds-input-date>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use Non-ISO Date Strings\n\n`value`, `min`, and `max` must be ISO 8601 date strings (`YYYY-MM-DD`). Any other format is passed to `DateTime.fromISO`, which marks the date invalid: a non-ISO `value` immediately trips validation, and a non-ISO `min` / `max` is silently ignored.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date value=\"31/12/2026\" max=\"31-12-2026\"></mds-input-date>\n\n<!-- CORRECT -->\n<mds-input-date value=\"2026-12-31\" max=\"2026-12-31\"></mds-input-date>\n```\n\n#### Do Not Hardcode `variant=\"error\"` to Signal Validation\n\nThe component manages `variant` automatically: it sets `'error'` when validation fails and restores `'primary'` when it passes. Hardcoding `variant=\"error\"` shows an error before the user has done anything, does not stop the submit, and is overwritten as soon as the user touches the field.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date name=\"dataScadenza\" variant=\"error\"></mds-input-date>\n\n<!-- CORRECT - let validation drive variant; listen to mdsInputValidation instead -->\n<mds-input-date name=\"dataScadenza\" required></mds-input-date>\n```\n\n#### Do Not Listen to the Native `change` or `input` Events\n\nThe component emits `mdsInputDateSelect` (value string) and `mdsInputValidation` (boolean). The native `change` event does not cross the shadow boundary, and `input` misses calendar-driven picks and values set from script.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date id=\"picker\" name=\"data\"></mds-input-date>\n<script>\n document.getElementById('picker').addEventListener('change', handler);\n</script>\n\n<!-- CORRECT -->\n<mds-input-date id=\"picker\" name=\"data\"></mds-input-date>\n<script>\n document.getElementById('picker').addEventListener('mdsInputDateSelect', handler);\n</script>\n```\n\n#### Do Not Use a Raw `<input type=\"date\">` as a Drop-in Replacement\n\nReplacing `<mds-input-date>` with a plain `<input type=\"date\">` loses form-association conventions, theming, the calendar overlay, the contextual tip, and all Magma accessibility defaults.\n\n```html\n<!-- INCORRECT -->\n<input type=\"date\" name=\"dataEvento\" />\n\n<!-- CORRECT -->\n<mds-input-date name=\"dataEvento\"></mds-input-date>\n```\n\n#### Do Not Set `disabled=\"false\"` or `readonly=\"false\"` to Remove the State\n\nBoolean attributes must be absent to be off. `mds-input-date` is form-associated, so as on a native control any value turns them on, `\"false\"` included: this markup renders a disabled, read-only field.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date name=\"data\" disabled=\"false\" readonly=\"false\"></mds-input-date>\n\n<!-- CORRECT - remove the attribute entirely -->\n<mds-input-date name=\"data\"></mds-input-date>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Inner Input\n\nThe documented customization surface is the public `--mds-input-date-*` CSS custom properties plus the `::part(input-date)` part. Targeting internals with `>>>`, `/deep/`, or undocumented selectors will break on any minor release.\n\n```css\n/* INCORRECT */\nmds-input-date >>> .input {\n border: 2px solid red;\n}\n\n/* CORRECT */\nmds-input-date {\n --mds-input-date-ring: 0 0 0 2px rgb(var(--magma-danger-border) / 0.8);\n}\nmds-input-date::part(input-date) {\n font-size: var(--text-size-info-caption);\n}\n```\n\n#### Do Not Set `value` to Clear the Field\n\nSetting `value=\"\"` is the correct way to clear; do not set `value` to a non-ISO string expecting the component to silently ignore it - it passes through validation and trips an error state.\n\n```html\n<!-- INCORRECT (non-ISO value to \"reset\") -->\n<mds-input-date name=\"data\" value=\"clear\"></mds-input-date>\n\n<!-- CORRECT -->\n<mds-input-date name=\"data\" value=\"\"></mds-input-date>\n```\n"
15172
15603
  },
15173
15604
  "props": [
@@ -15241,7 +15672,7 @@
15241
15672
  "mutable": false,
15242
15673
  "attr": "disabled",
15243
15674
  "reflectToAttr": true,
15244
- "docs": "If true, the element is displayed as disabled",
15675
+ "docs": "If true, the element is displayed as disabled. The calendar button is not shown: the end of\nthe field is left to the badge of its state",
15245
15676
  "docsTags": [
15246
15677
  {
15247
15678
  "name": "default",
@@ -15408,7 +15839,7 @@
15408
15839
  "mutable": false,
15409
15840
  "attr": "readonly",
15410
15841
  "reflectToAttr": true,
15411
- "docs": "Specifies that the element is read-only",
15842
+ "docs": "Specifies that the element is read-only: the date cannot be typed, and the calendar button is\nnot shown, as on a disabled field",
15412
15843
  "docsTags": [
15413
15844
  {
15414
15845
  "name": "default",
@@ -15798,24 +16229,6 @@
15798
16229
  "annotation": "prop",
15799
16230
  "docs": "The background of the input tip",
15800
16231
  "visibility": "public"
15801
- },
15802
- {
15803
- "name": "--mds-input-tip-horizontal-offset",
15804
- "annotation": "prop",
15805
- "docs": "The horizontal offset for the input tip",
15806
- "visibility": "internal"
15807
- },
15808
- {
15809
- "name": "--mds-input-tip-horizontal-offset-focused",
15810
- "annotation": "prop",
15811
- "docs": "The horizontal offset when the input tip is focused",
15812
- "visibility": "internal"
15813
- },
15814
- {
15815
- "name": "--mds-input-tip-vertical-offset",
15816
- "annotation": "prop",
15817
- "docs": "The vertical offset for the input tip",
15818
- "visibility": "internal"
15819
16232
  }
15820
16233
  ],
15821
16234
  "slots": [],
@@ -15843,8 +16256,8 @@
15843
16256
  "mds-calendar"
15844
16257
  ],
15845
16258
  "mds-button": [
15846
- "mds-spinner",
15847
16259
  "mds-icon",
16260
+ "mds-spinner",
15848
16261
  "mds-text"
15849
16262
  ],
15850
16263
  "mds-input-tip-item": [
@@ -15885,8 +16298,8 @@
15885
16298
  }
15886
16299
  ],
15887
16300
  "usage": {
15888
- "1. Description": "The `<mds-input-date-range>` web component is the Magma Design System control for capturing a start/end date pair, composing two slotted `<mds-input-date>` fields with a shared pop-up `mds-calendar` (in range mode) and optional quick-pick presets. It is a form-associated compound parent that orchestrates its children rather than rendering its own native inputs.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects exactly two `<mds-input-date>` children assigned to the `start` and `end` named slots; the host keeps both in sync as a single range - it is not meant to be used with a default (text) slot.\n- **Form association**: The submitted value is a JSON string `{ startDate, endDate }`; an empty range submits no value. On form reset it restores the start/end dates present at first load.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables its calendar button as `disabled` does, while the slotted fields, being inside the fieldset too, follow it themselves: the range cannot be changed and is left out of the form, until the fieldset is enabled.\n- **Range coercion**: When both dates are valid and the end falls before the start, the end is snapped to equal the start, also for a preselection that ends before it starts, so the committed range is never inverted.\n- **Min/max guard**: If `max` is earlier than `min` at load, `max` is clamped up to `min`; both bounds are forwarded to the calendar to block out-of-range selection, and to the slotted fields, which flag a date typed outside them and stop the submit; such a range is not emitted.\n- **Commit on blur**: Leaving the component validates the range, syncs the form value, and - when both dates are valid - emits selection.\n- **Calendar selection**: Picking a complete range in the pop-up calendar emits selection and, unless `delay` is `0`, auto-closes the dropdown after the delay.\n- **Preselection sync**: Slotted `mds-input-date-range-preselection` children act as quick-picks; activating one applies its range, and any external/calendar change re-evaluates which preset (if any) is marked selected; a preset matching the dates of load is marked selected from the start.\n- **Emitted events**: `mdsInputDateRangeValueChange` fires when a full, valid range is committed (calendar pick, preset, or focus-out with two valid dates) and either bound actually changed since the last emit.\n- **Focus management**: Clicking the host or either field label focuses the corresponding date input; a built-in calendar icon button, named in the page language (the `lang` of `<html>`) (\"Open calendar\"), toggles the calendar dropdown.\n- **Localization**: The \"from\"/\"to\" field labels and the calendar honor the resolved language (el/en/es/it).\n\n#### Properties & Visual Configurations\n\n- **`startDate` / `endDate`** are the controlled range bounds in ISO `YYYY-MM-DD` form; changing them externally re-syncs the slotted inputs and the calendar.\n- **`min` / `max`** define the selectable window: the calendar blocks the dates outside it, and the host passes both bounds to the slotted fields, which check a typed date against them. A bound the range does not set leaves the one written on a field alone; one changed after load reaches both fields.\n- **`disabled`** disables the range, like a disabled native input: the calendar button is disabled, a calendar left open closes, and the dates are left out of the form. It disables the two slotted fields too: at load only when it is set, so a field disabled on its own stays disabled; a change after load reaches both fields.\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner calendar button scale with it.\n- **`delay`** is the auto-close grace period (ms) after a complete selection; set it to `0` to keep the calendar open until the user dismisses it manually.\n",
15889
- "2. Examples": "Correct and idiomatic ways to use the `<mds-input-date-range>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Minimal Range Picker\n\nThe canonical form. Slot one [`mds-input-date`](../mds-input-date/AGENTS.md) as `start` and another as `end`; the host wires them together, drives the shared calendar, and handles range validation automatically.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Pre-filling the Range\n\nUse the `start-date` and `end-date` attributes to set an initial selection. Both expect ISO `YYYY-MM-DD` strings. Changing them later re-syncs the slotted inputs and the calendar automatically.\n\n```html\n<mds-input-date-range start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Constraining the Selectable Window\n\nUse `min` and `max` to block out-of-window dates in the calendar. Both are ISO `YYYY-MM-DD` strings. The host passes them to the slotted fields too: a date typed out of the window turns its field to error, stops the submit of the form and is not emitted as a range.\n\n```html\n<mds-input-date-range min=\"2026-01-01\" max=\"2026-12-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Listening to Range Events\n\n`mdsInputDateRangeValueChange` fires when a full, valid range is committed (calendar pick, preset, or focus-out with two valid dates) and either bound actually changed since the last emit. It delivers `{ startDate, endDate }` in `event.detail`.\n\n```html\n<mds-input-date-range id=\"periodo\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<script>\n document.querySelector('#periodo').addEventListener('mdsInputDateRangeValueChange', (e) => {\n console.log('Intervallo selezionato:', e.detail.startDate, '-', e.detail.endDate);\n });\n</script>\n```\n\n#### Form Participation\n\n`<mds-input-date-range>` is form-associated. Add `name` and place it inside a `<form>`; the submitted value is a JSON string `{ startDate, endDate }`. An empty range submits no value. Form reset restores the dates set at first load.\n\n```html\n<form action=\"/filtra\" method=\"get\">\n <mds-input-date-range name=\"periodo\" start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n </mds-input-date-range>\n <mds-button type=\"submit\" label=\"Applica filtro\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Reimposta\" variant=\"dark\" tone=\"outline\"></mds-button>\n</form>\n```\n\n#### Quick-Pick Preselections\n\nSlot one or more [`mds-input-date-range-preselection`](../mds-input-date-range-preselection/AGENTS.md) elements into the component. They appear inside the calendar dropdown and act as one-click range shortcuts. The host marks the matching preset as selected, from load on and whenever the range changes to match it. A preset whose end comes before its start applies its start as both ends.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n <mds-input-date-range-preselection start=\"2026-06-02\" end=\"2026-06-08\">\n Questa settimana\n </mds-input-date-range-preselection>\n <mds-input-date-range-preselection start=\"2026-06-01\" end=\"2026-06-30\">\n Questo mese\n </mds-input-date-range-preselection>\n</mds-input-date-range>\n```\n\n#### Controlling the Auto-Close Delay\n\nBy default the calendar closes 500 ms after a complete range is picked. Set `delay=\"0\"` to keep it open until the user dismisses it manually, or increase the value for a longer grace period.\n\n```html\n<!-- Keep the calendar open after selection -->\n<mds-input-date-range delay=\"0\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<!-- Longer grace period: 1 second -->\n<mds-input-date-range delay=\"1000\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Styling Customization\n\nStyle the component only through its public `--mds-input-date-range-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` ([`agents/color.md`](../../../../agents/color.md)) so dark mode and themes keep working.\n\n```css\n.filtro-avanzato mds-input-date-range {\n --mds-input-date-range-background: rgb(var(--magma-surface-sunken));\n --mds-input-date-range-fields-gap: 0 calc(var(--spacing) * 400);\n}\n```\n",
16301
+ "1. Description": "The `<mds-input-date-range>` web component is the Magma Design System control for capturing a start/end date pair, composing two slotted `<mds-input-date>` fields with a shared pop-up `mds-calendar` (in range mode) and optional quick-pick presets. It is a form-associated compound parent that orchestrates its children rather than rendering its own native inputs.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects exactly two `<mds-input-date>` children assigned to the `start` and `end` named slots; the host keeps both in sync as a single range - it is not meant to be used with a default (text) slot.\n- **Form association**: The submitted value is a JSON string `{ startDate, endDate }`; an empty range submits no value. On form reset it restores the start/end dates present at first load.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables its calendar button as `disabled` does, while the slotted fields, being inside the fieldset too, follow it themselves: the range cannot be changed and is left out of the form, until the fieldset is enabled.\n- **Range coercion**: When both dates are valid and the end falls before the start, the end is snapped to equal the start, also for a preselection that ends before it starts, so the committed range is never inverted.\n- **Min/max guard**: If `max` is earlier than `min` at load, `max` is clamped up to `min`; both bounds are forwarded to the calendar to block out-of-range selection, and to the slotted fields, which flag a date typed outside them and stop the submit; such a range is not emitted.\n- **Commit on blur**: Leaving the component validates the range, syncs the form value, and - when both dates are valid - emits selection.\n- **Active end**: the calendar picks one end of the range at a time, the active one. The field the user goes into names it, by focus or by a click: the \"from\" field the start, the \"to\" field the end. With no field named yet, it is the end the range lacks (the start of an empty range, the end of a range with its start alone), else the start. With no start the calendar always picks the start: a range is picked from its start.\n- **Header**: the top of the panel shows the two ends, \"Start\" and \"End\", each with its date or \"Pick a date\", as an [`mds-tab`](../mds-tab/AGENTS.md) of two voices; the voice of the active end is selected, and a click or Enter / Space on a voice makes its end the active one. The end has nothing to pick, and its voice is disabled, until the range has a start. The words follow the page language, as \"from\" and \"to\".\n- **Calendar selection**: a click in the calendar changes the active end only, also on a complete range, which is no longer started again from scratch; then the end is the active one, so a range is picked with two clicks, start then end, and a second click corrects the end. A click never swaps the ends: a day before the start, while the end is picked, becomes the new start and the end is still to pick; a day after the end, while the start is picked, becomes the new start and the end is emptied. A click that completes the range emits selection; when it picks the end it also closes the dropdown after `delay`, unless `delay` is `0`, while one that picks the start leaves it open for the end.\n- **Preselection sync**: Slotted `mds-input-date-range-preselection` children act as quick-picks; activating one applies its range, and any external/calendar change re-evaluates which preset (if any) is marked selected; a preset matching the dates of load is marked selected from the start.\n- **Emitted events**: `mdsInputDateRangeValueChange` fires when a full, valid range is committed (calendar pick, preset, or focus-out with two valid dates) and either bound actually changed since the last emit.\n- **Focus management**: Clicking the host or either field label focuses the corresponding date input, and makes its end the active one; a built-in calendar icon button, named in the page language (the `lang` of `<html>`) (\"Open calendar\"), toggles the calendar dropdown. A pick in the calendar leaves the focus where it is: the header says which end comes next.\n- **Localization**: The \"from\"/\"to\" field labels, the words of the header and the calendar honor the resolved language (el/en/es/it).\n\n#### Properties & Visual Configurations\n\n- **`startDate` / `endDate`** are the controlled range bounds in ISO `YYYY-MM-DD` form; changing them externally re-syncs the slotted inputs and the calendar.\n- **`min` / `max`** define the selectable window: the calendar blocks the dates outside it, and the host passes both bounds to the slotted fields, which check a typed date against them. A bound the range does not set leaves the one written on a field alone; one changed after load reaches both fields.\n- **`disabled`** disables the range, like a disabled native input: the calendar button is disabled, a calendar left open closes, and the dates are left out of the form. It disables the two slotted fields too: at load only when it is set, so a field disabled on its own stays disabled; a change after load reaches both fields.\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner calendar button scale with it.\n- **`delay`** is the auto-close grace period (ms) after the click that picks the end of the range; set it to `0` to keep the calendar open until the user dismisses it manually.\n- **`dualCalendar`** shows two consecutive months side by side instead of one, whatever the width of the page; the grids of the two months start at the same height, a month of five weeks next to one of six.\n",
16302
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-input-date-range>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Minimal Range Picker\n\nThe canonical form. Slot one [`mds-input-date`](../mds-input-date/AGENTS.md) as `start` and another as `end`; the host wires them together, drives the shared calendar, and handles range validation automatically.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Picking a Range in the Calendar\n\nThe calendar picks one end at a time: the one of the field the user went into, or the one selected in the header at the top of the panel. In an empty range the first click picks the start and the header passes to the end; the second click picks the end and, after `delay`, closes the panel. To change one end of a complete range, go into its field (or select its voice in the header) and click the new day: the other end stays. A day before the start, picked as the end, becomes the new start; a day after the end, picked as the start, becomes the new start and empties the end. Nothing needs configuring: the markup is the one of the minimal picker.\n\n```html\n<mds-input-date-range start-date=\"2026-03-10\" end-date=\"2026-03-19\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Pre-filling the Range\n\nUse the `start-date` and `end-date` attributes to set an initial selection. Both expect ISO `YYYY-MM-DD` strings. Changing them later re-syncs the slotted inputs and the calendar automatically.\n\n```html\n<mds-input-date-range start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Constraining the Selectable Window\n\nUse `min` and `max` to block out-of-window dates in the calendar. Both are ISO `YYYY-MM-DD` strings. The host passes them to the slotted fields too: a date typed out of the window turns its field to error, stops the submit of the form and is not emitted as a range.\n\n```html\n<mds-input-date-range min=\"2026-01-01\" max=\"2026-12-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Listening to Range Events\n\n`mdsInputDateRangeValueChange` fires when a full, valid range is committed (calendar pick, preset, or focus-out with two valid dates) and either bound actually changed since the last emit. It delivers `{ startDate, endDate }` in `event.detail`.\n\n```html\n<mds-input-date-range id=\"periodo\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<script>\n document.querySelector('#periodo').addEventListener('mdsInputDateRangeValueChange', (e) => {\n console.log('Intervallo selezionato:', e.detail.startDate, '-', e.detail.endDate);\n });\n</script>\n```\n\n#### Form Participation\n\n`<mds-input-date-range>` is form-associated. Add `name` and place it inside a `<form>`; the submitted value is a JSON string `{ startDate, endDate }`. An empty range submits no value. Form reset restores the dates set at first load.\n\n```html\n<form action=\"/filtra\" method=\"get\">\n <mds-input-date-range name=\"periodo\" start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n </mds-input-date-range>\n <mds-button type=\"submit\" label=\"Applica filtro\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Reimposta\" variant=\"dark\" tone=\"outline\"></mds-button>\n</form>\n```\n\n#### Quick-Pick Preselections\n\nSlot one or more [`mds-input-date-range-preselection`](../mds-input-date-range-preselection/AGENTS.md) elements into the component. They appear inside the calendar dropdown and act as one-click range shortcuts. The host marks the matching preset as selected, from load on and whenever the range changes to match it. A preset whose end comes before its start applies its start as both ends.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n <mds-input-date-range-preselection start=\"2026-06-02\" end=\"2026-06-08\">\n Questa settimana\n </mds-input-date-range-preselection>\n <mds-input-date-range-preselection start=\"2026-06-01\" end=\"2026-06-30\">\n Questo mese\n </mds-input-date-range-preselection>\n</mds-input-date-range>\n```\n\n#### Controlling the Auto-Close Delay\n\nBy default the calendar closes 500 ms after the click that picks the end of the range; a click that picks the start leaves it open for the end. Set `delay=\"0\"` to keep it open until the user dismisses it manually, or increase the value for a longer grace period.\n\n```html\n<!-- Keep the calendar open after selection -->\n<mds-input-date-range delay=\"0\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<!-- Longer grace period: 1 second -->\n<mds-input-date-range delay=\"1000\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Styling Customization\n\nStyle the component only through its public `--mds-input-date-range-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` ([`agents/color.md`](../../../../agents/color.md)) so dark mode and themes keep working.\n\n```css\n.filtro-avanzato mds-input-date-range {\n --mds-input-date-range-background: rgb(var(--magma-surface-sunken));\n --mds-input-date-range-fields-gap: 0 calc(var(--spacing) * 400);\n}\n```\n",
15890
16303
  "3. Mistakes": "Common incorrect uses of `<mds-input-date-range>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Omit the Named Slots\n\nThe host renders two named slots (`start` and `end`) and wires them together internally. Without slotted `<mds-input-date>` children the component has no visible inputs and no data to commit.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Slot Raw `<input>` Elements\n\nThe `start` and `end` slots expect [`mds-input-date`](../mds-input-date/AGENTS.md) children. The host calls `.setValue()` and `.focusInput()` on the assigned element; a native `<input>` does not expose those methods and will break internal orchestration.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range>\n <input type=\"date\" slot=\"start\" />\n <input type=\"date\" slot=\"end\" />\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Disable the Fields Instead of the Range\n\nDisabling the slotted fields leaves the calendar button of the range enabled, and the user can still change the dates from the calendar. Set `disabled` on the range: it disables its calendar button and the two fields, and leaves the dates out of the form.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range name=\"period\">\n <mds-input-date slot=\"start\" disabled></mds-input-date>\n <mds-input-date slot=\"end\" disabled></mds-input-date>\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range name=\"period\" disabled>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Use Non-ISO Date Strings\n\n`startDate`, `endDate`, `min`, and `max` all require `YYYY-MM-DD` ISO format. Passing a locale-formatted string (e.g. `\"01/06/2026\"`) is silently invalid for Luxon's `DateTime.fromISO()` and leaves the range empty or unguarded.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range start-date=\"01/06/2026\" end-date=\"30/06/2026\" min=\"01/01/2026\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range start-date=\"2026-06-01\" end-date=\"2026-06-30\" min=\"2026-01-01\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Listen to Native `change` or `input` Events\n\nThe component emits `mdsInputDateRangeValueChange` as a documented custom event. Native `change` / `input` events originate from inside the shadow DOM and do not bubble out reliably.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range id=\"range\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n<script>\n document.querySelector('#range').addEventListener('change', handler);\n</script>\n\n<!-- CORRECT -->\n<mds-input-date-range id=\"range\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n<script>\n document.querySelector('#range').addEventListener('mdsInputDateRangeValueChange', handler);\n</script>\n```\n\n#### Do Not Set `delay=\"false\"` to Disable Auto-Close\n\n`delay` is a numeric prop, not a boolean. The string `\"false\"` is parsed as `NaN`, which is not `0`: the dropdown then closes at once instead of staying open. Use `delay=\"0\"` to keep the calendar open after selection.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range delay=\"false\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range delay=\"0\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Slot Preselection Elements Without the Component's Calendar\n\n[`mds-input-date-range-preselection`](../mds-input-date-range-preselection/AGENTS.md) children must be direct children of `<mds-input-date-range>`. Outside the component a click finds no range to apply (the preset looks for its closest `mds-input-date-range`); inside a wrapper div the preset is not slotted into the calendar dropdown and never shows.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n<mds-input-date-range-preselection start=\"2026-06-01\" end=\"2026-06-30\">\n Questo mese\n</mds-input-date-range-preselection>\n\n<!-- CORRECT -->\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n <mds-input-date-range-preselection start=\"2026-06-01\" end=\"2026-06-30\">\n Questo mese\n </mds-input-date-range-preselection>\n</mds-input-date-range>\n```\n\n#### Do Not Omit `name` When Inside a Form\n\nWithout `name` the component is form-associated but submits no named field, so the date range is invisible to the server and to `FormData`.\n\n```html\n<!-- INCORRECT -->\n<form action=\"/filtra\" method=\"get\">\n <mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n </mds-input-date-range>\n</form>\n\n<!-- CORRECT -->\n<form action=\"/filtra\" method=\"get\">\n <mds-input-date-range name=\"periodo\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n </mds-input-date-range>\n</form>\n```\n"
15891
16304
  },
15892
16305
  "props": [
@@ -15927,7 +16340,7 @@
15927
16340
  "mutable": false,
15928
16341
  "attr": "delay",
15929
16342
  "reflectToAttr": true,
15930
- "docs": "Specifies the delay in milliseconds before closing the calendar dropdown, if the value is 0 the dropdown will not close",
16343
+ "docs": "Specifies the delay in milliseconds before closing the calendar dropdown after the click that\npicks the end of the range, if the value is 0 the dropdown will not close; a click that picks\nthe start leaves it open for the end",
15931
16344
  "docsTags": [
15932
16345
  {
15933
16346
  "name": "description",
@@ -16403,6 +16816,8 @@
16403
16816
  "states": [],
16404
16817
  "dependents": [],
16405
16818
  "dependencies": [
16819
+ "mds-tab",
16820
+ "mds-tab-item",
16406
16821
  "mds-calendar",
16407
16822
  "mds-text",
16408
16823
  "mds-button",
@@ -16410,20 +16825,25 @@
16410
16825
  ],
16411
16826
  "dependencyGraph": {
16412
16827
  "mds-input-date-range": [
16828
+ "mds-tab",
16829
+ "mds-tab-item",
16413
16830
  "mds-calendar",
16414
16831
  "mds-text",
16415
16832
  "mds-button",
16416
16833
  "mds-dropdown"
16417
16834
  ],
16418
- "mds-calendar": [
16419
- "mds-button",
16420
- "mds-calendar-cell"
16835
+ "mds-tab-item": [
16836
+ "mds-button"
16421
16837
  ],
16422
16838
  "mds-button": [
16423
- "mds-spinner",
16424
16839
  "mds-icon",
16840
+ "mds-spinner",
16425
16841
  "mds-text"
16426
16842
  ],
16843
+ "mds-calendar": [
16844
+ "mds-button",
16845
+ "mds-calendar-cell"
16846
+ ],
16427
16847
  "mds-calendar-cell": [
16428
16848
  "mds-button"
16429
16849
  ]
@@ -16622,8 +17042,8 @@
16622
17042
  "mds-button"
16623
17043
  ],
16624
17044
  "mds-button": [
16625
- "mds-spinner",
16626
17045
  "mds-icon",
17046
+ "mds-spinner",
16627
17047
  "mds-text"
16628
17048
  ]
16629
17049
  },
@@ -17031,8 +17451,8 @@
17031
17451
  "mds-spinner"
17032
17452
  ],
17033
17453
  "mds-button": [
17034
- "mds-spinner",
17035
17454
  "mds-icon",
17455
+ "mds-spinner",
17036
17456
  "mds-text"
17037
17457
  ],
17038
17458
  "mds-input-tip-item": [
@@ -17058,7 +17478,7 @@
17058
17478
  },
17059
17479
  {
17060
17480
  "name": "slot",
17061
- "text": "- Add `text string`, `HTML elements` or `components` to this slot."
17481
+ "text": "- The label of the range, as text. Add an `mds-input-range-value` per value to hold\nseveral values, a thumb each, on one track"
17062
17482
  },
17063
17483
  {
17064
17484
  "name": "category",
@@ -17066,9 +17486,9 @@
17066
17486
  }
17067
17487
  ],
17068
17488
  "usage": {
17069
- "1. Description": "The `<mds-input-range>` web component is the Magma Design System slider control for picking a single numeric value from a continuous interval. It wraps a native `<input type=\"range\">`, adding a labelled header, a styled track with a live progress fill, form association, and value formatting.\n\n#### Semantic Behavior\n\n- **Form association**: Inside a `<form>` the selected number is reported under `name` with no extra wiring. A form reset brings back the value of load, thumb and progress included, or the middle of the range when the markup sets no `value`, like a native input.\n- **Value clamping and snapping**: On input the value is clamped into `[min, max]` and snapped to the nearest `step` increment, so the committed `value` is always valid even when set programmatically out of range.\n- **Decimal awareness**: The number of decimal places is derived from `step`, letting fractional steps snap correctly; as on a native input, a `step` that is not a positive number, from the start or set later, falls back to the default step, `1`.\n- **Disabled state**: Blocks interaction and clears the reported form value while disabled. A disabled `<fieldset>` around the component does the same, as it does a native input.\n- **Emitted event**: `mdsInputRangeChange` carries the new numeric value whenever `value` actually changes.\n- **Accessibility**: The control takes its accessible name from the slotted label text.\n- **Default slot is the label**: The default slot holds the field's text label, rendered in the header alongside the formatted current value.\n\n#### Properties & Visual Configurations\n\n- **`min` / `max` / `step`** define the permitted interval and granularity; `step` also controls how fractional values are snapped and how many decimals are preserved.\n- **`value`** is the committed numeric selection, kept clamped and snapped - set it programmatically to move the thumb.\n- **`formatValue`** is a function `(value: number) => string` for presentation only: use it to render the header value as currency, a percentage, or a unit-suffixed label without changing the underlying numeric `value`.\n\nThis component does not use the shared `variant` / `tone` ladders ([`agents/variants.md`](../../../../agents/variants.md)); it has no public CSS custom property: the thumb and the track follow the theme, and the `header` and `track` parts listed in [`AGENTS.md`](AGENTS.md) are its styling hooks.\n",
17070
- "2. Examples": "Correct and idiomatic ways to use the `<mds-input-range>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Slider with a Label\n\nThe minimum viable form. Put the field's text label in the default slot - it is rendered in the header and used as the accessible name for the underlying input. The default range is 0-100 with a step of 1.\n\n```html\n<mds-input-range name=\"volume\">Volume</mds-input-range>\n```\n\n#### Setting `min`, `max`, and `step`\n\nConstrain the range to a meaningful interval. Use `step` to enforce granularity - the component snaps the selected value to the nearest multiple automatically.\n\n```html\n<!-- Percentage slider, 5-point increments -->\n<mds-input-range name=\"completamento\" min=\"0\" max=\"100\" step=\"5\">Completamento (%)</mds-input-range>\n\n<!-- Temperature slider, half-degree steps -->\n<mds-input-range name=\"temperatura\" min=\"16\" max=\"30\" step=\"0.5\">Temperatura (C)</mds-input-range>\n```\n\n#### Pre-selected Value via `value`\n\nPass `value` to initialize the thumb at a specific position. The prop is reflected, so it also stays in sync when the user drags.\n\n```html\n<mds-input-range name=\"priorita\" min=\"1\" max=\"10\" value=\"7\">Priorita</mds-input-range>\n```\n\n#### Listening to `mdsInputRangeChange`\n\nThe component emits `mdsInputRangeChange` with the new numeric value in `event.detail` whenever the committed value changes. Do not listen to the raw `input` or `change` events - they may not bubble out of shadow DOM as expected.\n\n```html\n<mds-input-range id=\"rating\" name=\"valutazione\" min=\"1\" max=\"5\">Valutazione</mds-input-range>\n\n<script>\n document.querySelector('#rating').addEventListener('mdsInputRangeChange', (event) => {\n console.log('Nuovo valore:', event.detail);\n });\n</script>\n```\n\n#### Custom Value Display with `formatValue`\n\nSupply a `(value: number) => string` function to `formatValue` to change how the current value is shown in the header label - for example to add a unit suffix, format as currency, or humanize byte counts. The underlying numeric `value` is not affected.\n\n```html\n<mds-input-range id=\"prezzo\" name=\"prezzo\" min=\"0\" max=\"10000\" step=\"50\">Prezzo massimo</mds-input-range>\n\n<script>\n document.querySelector('#prezzo').formatValue = (v) =>\n v.toLocaleString('it-IT', { style: 'currency', currency: 'EUR' });\n</script>\n```\n\n#### Disabled Slider\n\nSet the boolean `disabled` attribute to prevent interaction. The component applies disabled visual tokens and clears the reported form value automatically. Do not use `disabled=\"false\"` to re-enable - remove the attribute instead.\n\n```html\n<mds-input-range name=\"soglia\" min=\"0\" max=\"100\" value=\"40\" disabled>Soglia (disabilitato)</mds-input-range>\n```\n\n#### Form Participation\n\n`<mds-input-range>` is form-associated. Place it inside a `<form>` with a `name` attribute and the selected value is submitted automatically alongside other fields.\n\n```html\n<form action=\"/impostazioni\" method=\"post\">\n <mds-input-range name=\"luminosita\" min=\"0\" max=\"100\" value=\"75\">Luminosita</mds-input-range>\n <mds-input-range name=\"contrasto\" min=\"0\" max=\"100\" value=\"50\">Contrasto</mds-input-range>\n\n <mds-button type=\"submit\" label=\"Salva impostazioni\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Hiding the Header via `::part(header)`\n\nUse `::part(header)` to hide the label-and-value header when the surrounding UI already provides that context - for example in a compact settings row where the label lives outside the component.\n\n```css\n.slider-compatto mds-input-range::part(header) {\n display: none;\n}\n```\n\n#### Styling Customization\n\n`<mds-input-range>` has no public CSS custom property: the thumb and the track take their sizes from the component and their colours from the semantic color roles ([`agents/color.md`](../../../../agents/color.md)), the progress from the accent, so themes and dark mode recolour it without overrides. Adjust the slider only through its documented `header` and `track` parts, as in the example above.\n",
17071
- "3. Mistakes": "Common incorrect uses of `<mds-input-range>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Raw `<input type=\"range\">` Instead of the Component\n\nReaching for the native element bypasses the Magma-styled track, the progress fill, the labelled header, form association wiring, and the snapping logic.\n\n```html\n<!-- INCORRECT -->\n<label for=\"v\">Volume</label>\n<input type=\"range\" id=\"v\" name=\"volume\" min=\"0\" max=\"100\">\n\n<!-- CORRECT -->\n<mds-input-range name=\"volume\" min=\"0\" max=\"100\">Volume</mds-input-range>\n```\n\n#### Do Not Omit the Label Slot\n\nWithout slotted text the slider has no accessible name - screen readers cannot announce the control's purpose. Always put a meaningful text label in the default slot.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range name=\"luminosita\" min=\"0\" max=\"100\"></mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range name=\"luminosita\" min=\"0\" max=\"100\">Luminosita</mds-input-range>\n```\n\n#### Do Not Use `disabled=\"false\"` to Enable the Slider\n\n`disabled` is a boolean attribute and `mds-input-range` is form-associated: as on a native control, any value turns it on, `\"false\"` included, so this markup disables the slider. Remove the attribute entirely to enable it.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range name=\"soglia\" disabled=\"false\">Soglia</mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range name=\"soglia\">Soglia</mds-input-range>\n```\n\n#### Do Not Listen to Raw `input` / `change` Events\n\nNative events may not bubble out of shadow DOM the way you expect. Listen to `mdsInputRangeChange`, which the component emits on every committed value change.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range id=\"r\" name=\"valore\">Valore</mds-input-range>\n<script>\n document.querySelector('#r').addEventListener('change', (e) => {\n console.log(e.target.value); // unreliable across shadow DOM\n });\n</script>\n\n<!-- CORRECT -->\n<mds-input-range id=\"r\" name=\"valore\">Valore</mds-input-range>\n<script>\n document.querySelector('#r').addEventListener('mdsInputRangeChange', (e) => {\n console.log(e.detail); // numeric value, always reliable\n });\n</script>\n```\n\n#### Do Not Set `step` to Zero or a Negative Number\n\nA `step` of zero or negative is invalid: as on a native input it is ignored and the default step, `1`, applies instead, which is rarely the granularity you meant. Use a positive integer or decimal.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range name=\"q\" step=\"0\">Quantita</mds-input-range>\n<mds-input-range name=\"q\" step=\"-1\">Quantita</mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range name=\"q\" step=\"1\">Quantita</mds-input-range>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Track or Thumb\n\nThe component exposes `::part(header)` and `::part(track)` for all supported customization; it has no public CSS custom property, and the thumb and the track take their colours from the theme. Targeting internal class names via `>>>` or undocumented `::part()` names couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-input-range >>> .track-progress {\n background-color: hotpink;\n}\nmds-input-range::part(thumb) { /* \"thumb\" is not a documented part */\n border-radius: 0;\n}\n\n/* CORRECT */\nmds-input-range::part(track) { /* \"track\" is a documented part */\n opacity: 0.8;\n}\n```\n\n#### Do Not Use `formatValue` to Change the Submitted Form Value\n\n`formatValue` is purely presentational - it only changes the header display string. The submitted form value is always the raw number. Do not rely on it for data transformation.\n\n```html\n<!-- INCORRECT: expecting the form to submit the formatted string -->\n<mds-input-range id=\"p\" name=\"prezzo\">Prezzo</mds-input-range>\n<script>\n // This changes what is shown but NOT what is submitted\n document.querySelector('#p').formatValue = (v) => v + ' EUR';\n // form.submit() still sends a plain number for \"prezzo\"\n</script>\n\n<!-- CORRECT: format on the server or in a submit handler using event.detail -->\n<mds-input-range id=\"p\" name=\"prezzo\">Prezzo</mds-input-range>\n<script>\n document.querySelector('#p').formatValue = (v) =>\n v.toLocaleString('it-IT', { style: 'currency', currency: 'EUR' });\n // The display is formatted; handle raw numeric value on submit separately\n</script>\n```\n"
17489
+ "1. Description": "The `<mds-input-range>` web component is the Magma Design System slider control for picking a numeric value from a continuous interval, or several values on one track. It wraps a native `<input type=\"range\">` per thumb, adding a labelled header, a styled track with a live progress fill, form association, and value formatting.\n\n#### Semantic Behavior\n\n- **Form association**: Inside a `<form>` the selected number is reported under `name` with no extra wiring. A form reset brings back the value of load, thumb and progress included, or the middle of the range when the markup sets no `value`, like a native input.\n- **Value clamping and snapping**: On input the value is clamped into `[min, max]` and snapped to the nearest `step` increment, so the committed `value` is always valid even when set programmatically out of range.\n- **Decimal awareness**: The number of decimal places is derived from `step`, letting fractional steps snap correctly; as on a native input, a `step` that is not a positive number, from the start or set later, falls back to the default step, `1`.\n- **Disabled state**: Blocks interaction and clears the reported form value while disabled; enabled again, the range reports its value again. A disabled `<fieldset>` around the component does the same, as it does a native input.\n- **Emitted event**: `mdsInputRangeChange` carries the new numeric value whenever `value` actually changes.\n- **Accessibility**: The control takes its accessible name from the slotted label text; with `formatValue` it also announces the formatted value (`aria-valuetext`). The ring of the focus goes round the thumb.\n- **Default slot is the label**: The default slot holds the field's text label, rendered in the header alongside the formatted current value.\n- **Width**: The slider takes the width its container gives it, a narrow grid cell too: the track gets shorter and a label longer than the room left by the value ends in an ellipsis.\n\n#### Several Values on One Track\n\nAn [`<mds-input-range-value>`](../mds-input-range-value/AGENTS.md) child per value turns the range into a slider with a thumb per value, as an `<option>` per choice turns a `<select>` into a list: a minimum and a maximum, or the stops of a scale.\n\n- **From the first child on**: with one child or more, the values are the children's, one child included; `value` and `mdsInputRangeChange` are left out, and keep the one value of a range without children.\n- **One native input per thumb**: each thumb is a native range input, all of them stacked on the track. The native input gives the slider role, the value, the name, the focus and the drag; a component of `role=\"slider\"` elements would rewrite them, and leave the one value on another control.\n- **Neighbours bound each other**: a thumb never passes the thumbs next to it, but can reach them. The arrows move the thumb with the focus by one `step`, Page Up and Page Down by a tenth of the range, Home and End take it to its neighbours (or to `min` and `max`): the component handles these keys itself, because a native input knows only `min` and `max`.\n- **Order and limits of the markup**: the thumbs follow the values from the lowest, whatever the order of the children; each keeps the name of its own child. A value outside `min` and `max`, or off the step, is brought inside and onto the step, as a native input sanitizes it, and written back on its child; a child without a value starts in the middle.\n- **Names**: the text of the range names the group of thumbs, the text of each child names its thumb, as in the multi-thumb slider of the WAI-ARIA APG. A child without text gets the label and the position of its thumb (\"Prezzo, 1 di 2\", in the language of the page).\n- **Header**: the values in order, formatted as the one value: two are an interval joined by an en dash (\"20 - 80\" with a long dash), more a list joined by a middle dot.\n- **Fill**: from the first thumb to the last.\n- **Overlap**: a thumb is as wide as the track is tall, so two near values lie on each other: the thumb with the focus lies on top and the keys move it alone. Without the focus, a thumb held by its neighbours lies under them, so that the one on top can move.\n- **Pointer**: a thumb drags itself; a press on the track moves the nearest thumb there.\n- **Adding and removing**: adding a value is adding a child, removing one is removing it; the range watches its children, their values and their text.\n- **Form**: an entry per value under `name`, in order, as a native `<select multiple>`; a form reset gives each child back the value it had when the range first read it.\n- **Event**: `mdsInputRangeValuesChange` carries `{ values }`, in order, whenever the list changes: from a thumb, from code, as a child comes or goes, on a reset. The values of load are not a change.\n\n#### Properties & Visual Configurations\n\n- **`min` / `max` / `step`** define the permitted interval and granularity; `step` also controls how fractional values are snapped and how many decimals are preserved.\n- **`value`** is the committed numeric selection of a range without `<mds-input-range-value>` children, kept clamped and snapped - set it programmatically to move the thumb. With children, each child holds the value of its thumb.\n- **`formatValue`** is a function `(value: number) => string` for presentation only: use it to render the header value as currency, a percentage, or a unit-suffixed label without changing the underlying numeric `value`.\n\nThis component does not use the shared `variant` / `tone` ladders ([`agents/variants.md`](../../../../agents/variants.md)); it has no public CSS custom property: the thumb and the track follow the theme, and the `header` and `track` parts listed in [`AGENTS.md`](AGENTS.md) are its styling hooks.\n",
17490
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-input-range>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Slider with a Label\n\nThe minimum viable form. Put the field's text label in the default slot - it is rendered in the header and used as the accessible name for the underlying input. The default range is 0-100 with a step of 1.\n\n```html\n<mds-input-range name=\"volume\">Volume</mds-input-range>\n```\n\n#### Setting `min`, `max`, and `step`\n\nConstrain the range to a meaningful interval. Use `step` to enforce granularity - the component snaps the selected value to the nearest multiple automatically.\n\n```html\n<!-- Percentage slider, 5-point increments -->\n<mds-input-range name=\"completamento\" min=\"0\" max=\"100\" step=\"5\">Completamento (%)</mds-input-range>\n\n<!-- Temperature slider, half-degree steps -->\n<mds-input-range name=\"temperatura\" min=\"16\" max=\"30\" step=\"0.5\">Temperatura (C)</mds-input-range>\n```\n\n#### Pre-selected Value via `value`\n\nPass `value` to initialize the thumb at a specific position. The prop is reflected, so it also stays in sync when the user drags.\n\n```html\n<mds-input-range name=\"priorita\" min=\"1\" max=\"10\" value=\"7\">Priorita</mds-input-range>\n```\n\n#### Listening to `mdsInputRangeChange`\n\nThe component emits `mdsInputRangeChange` with the new numeric value in `event.detail` whenever the committed value changes. Do not listen to the raw `input` or `change` events - they may not bubble out of shadow DOM as expected.\n\n```html\n<mds-input-range id=\"rating\" name=\"valutazione\" min=\"1\" max=\"5\">Valutazione</mds-input-range>\n\n<script>\n document.querySelector('#rating').addEventListener('mdsInputRangeChange', (event) => {\n console.log('Nuovo valore:', event.detail);\n });\n</script>\n```\n\n#### Custom Value Display with `formatValue`\n\nSupply a `(value: number) => string` function to `formatValue` to change how the current value is shown in the header label - for example to add a unit suffix, format as currency, or humanize byte counts. The underlying numeric `value` is not affected.\n\n```html\n<mds-input-range id=\"prezzo\" name=\"prezzo\" min=\"0\" max=\"10000\" step=\"50\">Prezzo massimo</mds-input-range>\n\n<script>\n document.querySelector('#prezzo').formatValue = (v) =>\n v.toLocaleString('it-IT', { style: 'currency', currency: 'EUR' });\n</script>\n```\n\n#### Disabled Slider\n\nSet the boolean `disabled` attribute to prevent interaction. The component applies disabled visual tokens and clears the reported form value automatically. Do not use `disabled=\"false\"` to re-enable - remove the attribute instead.\n\n```html\n<mds-input-range name=\"soglia\" min=\"0\" max=\"100\" value=\"40\" disabled>Soglia (disabilitato)</mds-input-range>\n```\n\n#### Form Participation\n\n`<mds-input-range>` is form-associated. Place it inside a `<form>` with a `name` attribute and the selected value is submitted automatically alongside other fields.\n\n```html\n<form action=\"/impostazioni\" method=\"post\">\n <mds-input-range name=\"luminosita\" min=\"0\" max=\"100\" value=\"75\">Luminosita</mds-input-range>\n <mds-input-range name=\"contrasto\" min=\"0\" max=\"100\" value=\"50\">Contrasto</mds-input-range>\n\n <mds-button type=\"submit\" label=\"Salva impostazioni\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Several Values: an Interval\n\nPut an [`<mds-input-range-value>`](../mds-input-range-value/AGENTS.md) per value inside the range: a thumb each. The text of the range is the label of the group, the text of each value names its thumb. The header shows the two values as an interval, formatted by `formatValue` as the one value.\n\n```html\n<mds-input-range id=\"prezzo-intervallo\" min=\"0\" max=\"500\" step=\"10\" name=\"prezzo\">\n Prezzo\n <mds-input-range-value value=\"100\">Minimo</mds-input-range-value>\n <mds-input-range-value value=\"400\">Massimo</mds-input-range-value>\n</mds-input-range>\n\n<script>\n document.querySelector('#prezzo-intervallo').formatValue = (v) =>\n v.toLocaleString('it-IT', { style: 'currency', currency: 'EUR' });\n</script>\n```\n\nThe form receives one entry per value under `name`, in order: `prezzo=100&prezzo=400`, read on the server as a list, as the entries of a `<select multiple>`.\n\n#### Several Values: Listening to `mdsInputRangeValuesChange`\n\nWith values, the range emits `mdsInputRangeValuesChange`, whose `detail.values` lists them in order from the lowest. It fires whenever the list changes: a thumb moved, a value set from code, a value added or removed, a form reset.\n\n```html\n<mds-input-range id=\"scala\" min=\"1\" max=\"21\" step=\"0.5\" name=\"contrasto\">\n Scala di contrasto\n <mds-input-range-value value=\"3\"></mds-input-range-value>\n <mds-input-range-value value=\"4.5\"></mds-input-range-value>\n <mds-input-range-value value=\"7\"></mds-input-range-value>\n <mds-input-range-value value=\"12\"></mds-input-range-value>\n</mds-input-range>\n\n<script>\n document.querySelector('#scala').addEventListener('mdsInputRangeValuesChange', (event) => {\n console.log('Passi:', event.detail.values); // [3, 4.5, 7, 12]\n });\n</script>\n```\n\nThe values without text are named after the label and their position (\"Scala di contrasto, 2 di 4\"). Adding a stop is appending an `<mds-input-range-value>`, removing one is removing it.\n\n#### Hiding the Header via `::part(header)`\n\nUse `::part(header)` to hide the label-and-value header when the surrounding UI already provides that context - for example in a compact settings row where the label lives outside the component.\n\n```css\n.slider-compatto mds-input-range::part(header) {\n display: none;\n}\n```\n\n#### Styling Customization\n\n`<mds-input-range>` has no public CSS custom property: the thumb and the track take their sizes from the component and their colours from the semantic color roles ([`agents/color.md`](../../../../agents/color.md)), the progress from the accent, so themes and dark mode recolour it without overrides. Adjust the slider only through its documented `header` and `track` parts, as in the example above.\n",
17491
+ "3. Mistakes": "Common incorrect uses of `<mds-input-range>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Raw `<input type=\"range\">` Instead of the Component\n\nReaching for the native element bypasses the Magma-styled track, the progress fill, the labelled header, form association wiring, and the snapping logic.\n\n```html\n<!-- INCORRECT -->\n<label for=\"v\">Volume</label>\n<input type=\"range\" id=\"v\" name=\"volume\" min=\"0\" max=\"100\">\n\n<!-- CORRECT -->\n<mds-input-range name=\"volume\" min=\"0\" max=\"100\">Volume</mds-input-range>\n```\n\n#### Do Not Omit the Label Slot\n\nWithout slotted text the slider has no accessible name - screen readers cannot announce the control's purpose. Always put a meaningful text label in the default slot.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range name=\"luminosita\" min=\"0\" max=\"100\"></mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range name=\"luminosita\" min=\"0\" max=\"100\">Luminosita</mds-input-range>\n```\n\n#### Do Not Use `disabled=\"false\"` to Enable the Slider\n\n`disabled` is a boolean attribute and `mds-input-range` is form-associated: as on a native control, any value turns it on, `\"false\"` included, so this markup disables the slider. Remove the attribute entirely to enable it.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range name=\"soglia\" disabled=\"false\">Soglia</mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range name=\"soglia\">Soglia</mds-input-range>\n```\n\n#### Do Not Listen to Raw `input` / `change` Events\n\nNative events may not bubble out of shadow DOM the way you expect. Listen to `mdsInputRangeChange`, which the component emits on every committed value change.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range id=\"r\" name=\"valore\">Valore</mds-input-range>\n<script>\n document.querySelector('#r').addEventListener('change', (e) => {\n console.log(e.target.value); // unreliable across shadow DOM\n });\n</script>\n\n<!-- CORRECT -->\n<mds-input-range id=\"r\" name=\"valore\">Valore</mds-input-range>\n<script>\n document.querySelector('#r').addEventListener('mdsInputRangeChange', (e) => {\n console.log(e.detail); // numeric value, always reliable\n });\n</script>\n```\n\n#### Do Not Set `step` to Zero or a Negative Number\n\nA `step` of zero or negative is invalid: as on a native input it is ignored and the default step, `1`, applies instead, which is rarely the granularity you meant. Use a positive integer or decimal.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range name=\"q\" step=\"0\">Quantita</mds-input-range>\n<mds-input-range name=\"q\" step=\"-1\">Quantita</mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range name=\"q\" step=\"1\">Quantita</mds-input-range>\n```\n\n#### Do Not Put Several Ranges Side by Side for One Interval\n\nTwo ranges for a minimum and a maximum let the minimum pass the maximum, and give the form two names. Put both values on one range.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range name=\"prezzo-min\" value=\"100\">Prezzo minimo</mds-input-range>\n<mds-input-range name=\"prezzo-max\" value=\"400\">Prezzo massimo</mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range name=\"prezzo\">\n Prezzo\n <mds-input-range-value value=\"100\">Minimo</mds-input-range-value>\n <mds-input-range-value value=\"400\">Massimo</mds-input-range-value>\n</mds-input-range>\n```\n\n#### Do Not Set `value` on a Range with Values\n\nWith `<mds-input-range-value>` children, the values are theirs: `value` of the range and `mdsInputRangeChange` are left out. Set and read the values on the children, or listen to `mdsInputRangeValuesChange`.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range value=\"20\">\n Prezzo\n <mds-input-range-value>Minimo</mds-input-range-value>\n <mds-input-range-value>Massimo</mds-input-range-value>\n</mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range>\n Prezzo\n <mds-input-range-value value=\"20\">Minimo</mds-input-range-value>\n <mds-input-range-value value=\"80\">Massimo</mds-input-range-value>\n</mds-input-range>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Track or Thumb\n\nThe component exposes `::part(header)` and `::part(track)` for all supported customization; it has no public CSS custom property, and the thumb and the track take their colours from the theme. Targeting internal class names via `>>>` or undocumented `::part()` names couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-input-range >>> .track-progress {\n background-color: hotpink;\n}\nmds-input-range::part(thumb) { /* \"thumb\" is not a documented part */\n border-radius: 0;\n}\n\n/* CORRECT */\nmds-input-range::part(track) { /* \"track\" is a documented part */\n opacity: 0.8;\n}\n```\n\n#### Do Not Use `formatValue` to Change the Submitted Form Value\n\n`formatValue` is purely presentational - it only changes the header display string. The submitted form value is always the raw number. Do not rely on it for data transformation.\n\n```html\n<!-- INCORRECT: expecting the form to submit the formatted string -->\n<mds-input-range id=\"p\" name=\"prezzo\">Prezzo</mds-input-range>\n<script>\n // This changes what is shown but NOT what is submitted\n document.querySelector('#p').formatValue = (v) => v + ' EUR';\n // form.submit() still sends a plain number for \"prezzo\"\n</script>\n\n<!-- CORRECT: format on the server or in a submit handler using event.detail -->\n<mds-input-range id=\"p\" name=\"prezzo\">Prezzo</mds-input-range>\n<script>\n document.querySelector('#p').formatValue = (v) =>\n v.toLocaleString('it-IT', { style: 'currency', currency: 'EUR' });\n // The display is formatted; handle raw numeric value on submit separately\n</script>\n```\n"
17072
17492
  },
17073
17493
  "props": [
17074
17494
  {
@@ -17246,7 +17666,7 @@
17246
17666
  "mutable": true,
17247
17667
  "attr": "value",
17248
17668
  "reflectToAttr": true,
17249
- "docs": "The value attribute contains a number which contains a representation of the selected number.",
17669
+ "docs": "The value attribute contains a number which contains a representation of the selected number.\nIt holds the one value of a range without `mds-input-range-value` children: with children the\nvalues are theirs, and this one is left out",
17250
17670
  "docsTags": [],
17251
17671
  "values": [
17252
17672
  {
@@ -17272,7 +17692,28 @@
17272
17692
  },
17273
17693
  "cancelable": true,
17274
17694
  "composed": true,
17275
- "docs": "Emits when the input range is changed",
17695
+ "docs": "Emits when the input range is changed: the value of a range without\n`mds-input-range-value` children",
17696
+ "docsTags": []
17697
+ },
17698
+ {
17699
+ "event": "mdsInputRangeValuesChange",
17700
+ "detail": "MdsInputRangeValuesEventDetail",
17701
+ "bubbles": true,
17702
+ "complexType": {
17703
+ "original": "MdsInputRangeValuesEventDetail",
17704
+ "resolved": "MdsInputRangeValuesEventDetail",
17705
+ "references": {
17706
+ "MdsInputRangeValuesEventDetail": {
17707
+ "location": "import",
17708
+ "path": "./meta/event-detail",
17709
+ "id": "src/components/mds-input-range/meta/event-detail.ts::MdsInputRangeValuesEventDetail",
17710
+ "referenceLocation": "MdsInputRangeValuesEventDetail"
17711
+ }
17712
+ }
17713
+ },
17714
+ "cancelable": true,
17715
+ "composed": true,
17716
+ "docs": "Emits when the values of a range with `mds-input-range-value` children change: from a thumb,\nfrom code, as a child comes or goes, or on a form reset. `values` holds them in order, from\nthe lowest. The values of load are not a change",
17276
17717
  "docsTags": []
17277
17718
  }
17278
17719
  ],
@@ -17336,7 +17777,7 @@
17336
17777
  "slots": [
17337
17778
  {
17338
17779
  "name": "",
17339
- "docs": "Add `text string`, `HTML elements` or `components` to this slot."
17780
+ "docs": "The label of the range, as text. Add an `mds-input-range-value` per value to hold\nseveral values, a thumb each, on one track"
17340
17781
  }
17341
17782
  ],
17342
17783
  "parts": [
@@ -17361,6 +17802,72 @@
17361
17802
  },
17362
17803
  "storybook": "form-range--docs"
17363
17804
  },
17805
+ {
17806
+ "filePath": "src/components/mds-input-range-value/mds-input-range-value.tsx",
17807
+ "encapsulation": "shadow",
17808
+ "tag": "mds-input-range-value",
17809
+ "readme": "# mds-input-range-value\n\n\n",
17810
+ "docs": "One value of an `mds-input-range` that holds several, as an `<option>` is one choice of a\n`<select>`: the range draws a thumb for it, and its text names that thumb. It draws nothing\nitself. Adding or removing a value is adding or removing one of these elements: the range\nwatches its children.",
17811
+ "docsTags": [
17812
+ {
17813
+ "name": "slot",
17814
+ "text": "- The name of the value, as text (\"Minimo\", \"Massimo\"): the accessible name of its thumb.\nWithout text the thumb is named after the label of the range and its position (\"Prezzo, 1 di 2\")"
17815
+ },
17816
+ {
17817
+ "name": "parent",
17818
+ "text": "mds-input-range"
17819
+ }
17820
+ ],
17821
+ "usage": {
17822
+ "1. Description": "The `<mds-input-range-value>` web component is one value of a [`<mds-input-range>`](../mds-input-range/AGENTS.md) that holds several values on one track, as an `<option>` is one choice of a `<select>`. The range draws a thumb for each of its `<mds-input-range-value>` children; the child itself draws nothing.\n\n#### Semantic Behavior\n\n- **Compound child only**: it works only as a direct child of `<mds-input-range>`. Outside a range it is hidden and does nothing.\n- **One child, one thumb**: adding a value is adding a child, removing one is removing its child. The range watches its children, their values and their text.\n- **The text names the thumb**: the text of the child is the accessible name of its thumb (\"Minimo\", \"Massimo\"), as each thumb of the multi-thumb slider of the WAI-ARIA APG. A child without text gets a name made of the label of the range and its position (\"Prezzo, 1 di 2\", in the language of the page).\n- **The range keeps the value valid**: it brings a value outside `min` and `max`, or off the `step`, inside the range and onto the step, as a native range input does, and writes it back here. A child without a value starts in the middle of the range.\n- **The order is the order of the values**: the thumbs follow their values from the lowest, whatever the order of the children in the markup; each keeps the name of its own child.\n- **The value follows the thumb**: as the thumb moves, the range writes its value on `value`, which is reflected. Setting `value` moves the thumb.\n\n#### Properties & Visual Configurations\n\nThe only prop is `value`, the number of the thumb. The thumb is styled by its range: the child has no `variant` / `tone` ([`agents/variants.md`](../../../../agents/variants.md)), no part and no public CSS custom property.\n",
17823
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-input-range-value>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### An Interval: Two Values\n\nThe canonical form: a minimum and a maximum on one track. The text of the range is its label, the text of each value names its thumb.\n\n```html\n<mds-input-range min=\"0\" max=\"500\" step=\"10\" name=\"prezzo\">\n Prezzo\n <mds-input-range-value value=\"100\">Minimo</mds-input-range-value>\n <mds-input-range-value value=\"400\">Massimo</mds-input-range-value>\n</mds-input-range>\n```\n\n#### A Scale of Stops\n\nMore than two values: each stops at its neighbours, which it can reach but not pass. The header lists them, separated by a middle dot.\n\n```html\n<mds-input-range min=\"1\" max=\"21\" step=\"0.5\" name=\"contrasto\">\n Scala di contrasto\n <mds-input-range-value value=\"3\">Passo 1</mds-input-range-value>\n <mds-input-range-value value=\"4.5\">Passo 2</mds-input-range-value>\n <mds-input-range-value value=\"7\">Passo 3</mds-input-range-value>\n <mds-input-range-value value=\"12\">Passo 4</mds-input-range-value>\n</mds-input-range>\n```\n\n#### Adding and Removing a Value\n\nA value is an element: append a child to add a thumb, remove it to take the thumb away. The range emits `mdsInputRangeValuesChange` with the new list.\n\n```html\n<mds-input-range id=\"scala\" min=\"0\" max=\"100\" name=\"passi\">\n Passi\n <mds-input-range-value value=\"20\"></mds-input-range-value>\n <mds-input-range-value value=\"80\"></mds-input-range-value>\n</mds-input-range>\n\n<script>\n const scala = document.querySelector('#scala');\n const passo = document.createElement('mds-input-range-value');\n passo.value = 50;\n scala.append(passo); // a third thumb at 50\n passo.remove(); // back to two\n</script>\n```\n\n#### Reading and Setting a Value\n\n`value` follows its thumb, so the children are where the page reads the values; setting `value` moves the thumb, within its neighbours.\n\n```js\nconst [minimo, massimo] = document.querySelectorAll('#prezzo mds-input-range-value');\nconsole.log(minimo.value, massimo.value);\nmassimo.value = 300;\n```\n",
17824
+ "3. Mistakes": "Common incorrect uses of `<mds-input-range-value>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use It Outside `<mds-input-range>`\n\nA value draws nothing: only its range draws its thumb.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range-value value=\"20\">Minimo</mds-input-range-value>\n\n<!-- CORRECT -->\n<mds-input-range min=\"0\" max=\"100\">\n Prezzo\n <mds-input-range-value value=\"20\">Minimo</mds-input-range-value>\n</mds-input-range>\n```\n\n#### Do Not Put the Label of the Range in a Value\n\nThe text of the range is its label, the text of a value names its own thumb. A value that carries the label leaves the range unnamed and names one thumb after the whole group.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range>\n <mds-input-range-value value=\"20\">Prezzo</mds-input-range-value>\n <mds-input-range-value value=\"80\"></mds-input-range-value>\n</mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range>\n Prezzo\n <mds-input-range-value value=\"20\">Minimo</mds-input-range-value>\n <mds-input-range-value value=\"80\">Massimo</mds-input-range-value>\n</mds-input-range>\n```\n\n#### Do Not Read the Values from `value` of the Range\n\nWith values, `value` and `mdsInputRangeChange` of the range are left out: they hold the one value of a range without children. Read the children, `mdsInputRangeValuesChange` or the form.\n\n```js\n// INCORRECT\nrange.addEventListener('mdsInputRangeChange', (e) => console.log(e.detail));\n\n// CORRECT\nrange.addEventListener('mdsInputRangeValuesChange', (e) => console.log(e.detail.values));\n```\n"
17825
+ },
17826
+ "props": [
17827
+ {
17828
+ "name": "value",
17829
+ "type": "number | undefined",
17830
+ "complexType": {
17831
+ "original": "number",
17832
+ "resolved": "number | undefined",
17833
+ "references": {}
17834
+ },
17835
+ "mutable": true,
17836
+ "attr": "value",
17837
+ "reflectToAttr": true,
17838
+ "docs": "The value of the thumb. The range keeps it inside its `min` and `max`, on its `step` and\nbetween the values next to it, and writes it here as the thumb moves; set it to move the\nthumb. Without a value the thumb starts in the middle of the range, as a native range input",
17839
+ "docsTags": [],
17840
+ "values": [
17841
+ {
17842
+ "type": "number"
17843
+ },
17844
+ {
17845
+ "type": "undefined"
17846
+ }
17847
+ ],
17848
+ "optional": true,
17849
+ "required": false,
17850
+ "getter": false,
17851
+ "setter": false
17852
+ }
17853
+ ],
17854
+ "methods": [],
17855
+ "events": [],
17856
+ "listeners": [],
17857
+ "styles": [],
17858
+ "slots": [
17859
+ {
17860
+ "name": "",
17861
+ "docs": "The name of the value, as text (\"Minimo\", \"Massimo\"): the accessible name of its thumb.\nWithout text the thumb is named after the label of the range and its position (\"Prezzo, 1 di 2\")"
17862
+ }
17863
+ ],
17864
+ "parts": [],
17865
+ "states": [],
17866
+ "dependents": [],
17867
+ "dependencies": [],
17868
+ "dependencyGraph": {},
17869
+ "storybook": "ui-forms-range-value--docs"
17870
+ },
17364
17871
  {
17365
17872
  "filePath": "src/components/mds-input-select/mds-input-select.tsx",
17366
17873
  "encapsulation": "shadow",
@@ -17386,7 +17893,7 @@
17386
17893
  }
17387
17894
  ],
17388
17895
  "usage": {
17389
- "1. Description": "The `<mds-input-select>` web component is the Magma Design System single- and multi-choice dropdown control. It wraps a native `<select>` element, adding form association, accessible status feedback, and themed chrome while accepting plain `<option>` elements through its default slot.\n\n#### Semantic Behavior\n\n- **Native select wrapping**: It renders a real `<select>` (exposed as the `select` part) so keyboard, type-ahead, and platform option lists work natively; the host owns theming and status only.\n- **Slotted options**: The default slot accepts `<option>` (and `<optgroup>`) markup; the current selection re-syncs whenever the slotted content changes.\n- **Form association**: The selection is pushed to the host form: a single select submits its `value`, a `multiple` one an entry per selected option under `name`, as a native select. A form reset brings back the selection of load, like a native select: the options the markup marks `selected` (or the placeholder), with the `value` of load on top. Toggling `disabled` removes the value from the submitted form data.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **Form validity**: A `required` select left empty is reported to the form as a native one: it matches `:invalid` and stops the submit, with a message in the page language. A disabled select is left out, and `novalidate` on the `<form>` turns the check off.\n- **Value syncing**: Changing the selection (by user input, the `setValue()` method, or the prop) emits `mdsInputSelectChange` with `{ value, values }` in `detail`: `value` is the first selected option as a string, `values` the values of every selected option, the placeholder left out. Like a native `<select>`, it is not emitted on load: the selection the component starts with reaches the form, not the event. A `value` set by code selects its `<option>` alone, as `select.value` does, and a value cleared by code goes back to the placeholder.\n- **Placeholder option**: When `placeholder` is set, a leading empty-value `<option>` is injected as the first entry; if `required` is set that placeholder is disabled so it cannot be re-selected after a valid choice.\n- **Default selection fallback**: With no explicit value, the options the markup marks `selected` become the selection; without them, the placeholder or, with no placeholder, the first option of a single select. A `defaultValue` seeds `value` at load.\n- **Status tip**: A status tip surfaces verbose state - a disabled notice, and for required fields a `required` / `required-success` message that expands while the control has focus.\n\n#### Properties & Visual Configurations\n\nThe `variant` prop applies a status appearance drawn from the shared status ladder in [`agents/variants.md`](../../../../agents/variants.md) - use it to reflect validation outcome (`'error'`, `'success'`, `'warning'`, `'info'`) rather than decorative styling. This component exposes no separate `tone` prop.\n\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner arrow scale with it.\n\n#### Other behavioral props\n\n- **`multiple`** turns the control into a multi-select list box: the form gets an entry per selected option and `values` in the `mdsInputSelectChange` detail lists them all, while `value` holds the first one, as `select.value` does. **`rows`** sets how many option rows are visible at once, as the `size` of a native `<select>`: above `1` it shows a list box even without `multiple`. A number in `size`, the row count it used to set, still works as `rows` but warns: it is deprecated and goes in the next major.\n- **`defaultValue`** is the initial selection used to seed the value at load (notably for the React wrapper), distinct from the live `value` that reflects the current choice.\n- **`required`** both enforces a non-empty submission and locks the placeholder option so the empty entry cannot be chosen again.\n",
17896
+ "1. Description": "The `<mds-input-select>` web component is the Magma Design System single- and multi-choice dropdown control. It wraps a native `<select>` element, adding form association, accessible status feedback, and themed chrome while accepting plain `<option>` elements through its default slot.\n\n#### Semantic Behavior\n\n- **Native select wrapping**: It renders a real `<select>` (exposed as the `select` part) so keyboard, type-ahead, and platform option lists work natively; the host owns theming and status only.\n- **Slotted options**: The default slot accepts `<option>` (and `<optgroup>`) markup; the current selection re-syncs whenever the slotted content changes.\n- **Form association**: The selection is pushed to the host form: a single select submits its `value`, a `multiple` one an entry per selected option under `name`, as a native select. A form reset brings back the selection of load, like a native select: the options the markup marks `selected` (or the placeholder), with the `value` of load on top. Toggling `disabled` removes the value from the submitted form data.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **Form validity**: A `required` select left empty is reported to the form as a native one: it matches `:invalid` and stops the submit, with a message in the page language. A disabled select is left out, and `novalidate` on the `<form>` turns the check off.\n- **Value syncing**: Changing the selection (by user input, the `setValue()` method, or the prop) emits `mdsInputSelectChange` with `{ value, values }` in `detail`: `value` is the first selected option as a string, `values` the values of every selected option, the placeholder left out. Like a native `<select>`, it is not emitted on load: the selection the component starts with reaches the form, not the event. A `value` set by code selects its `<option>` alone, as `select.value` does, and a value cleared by code goes back to the placeholder.\n- **Placeholder option**: When `placeholder` is set, a leading empty-value `<option>` is injected as the first entry; if `required` is set that placeholder is disabled so it cannot be re-selected after a valid choice.\n- **Default selection fallback**: With no explicit value, the options the markup marks `selected` become the selection; without them, the placeholder or, with no placeholder, the first option of a single select. A `defaultValue` seeds `value` at load.\n- **Status tip**: A status tip surfaces verbose state - a disabled notice, and for required fields a `required` / `required-success` message that expands while the control has focus. It stands on the top border of the field, half outside, clear of its rounded corner, and stays there while the control has the focus, as on `mds-input`: the arrow keeps its place.\n\n#### Properties & Visual Configurations\n\nThe `variant` prop applies a status appearance drawn from the shared status ladder in [`agents/variants.md`](../../../../agents/variants.md) - use it to reflect validation outcome (`'error'`, `'success'`, `'warning'`, `'info'`) rather than decorative styling. This component exposes no separate `tone` prop.\n\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner arrow scale with it.\n\n#### Other behavioral props\n\n- **`multiple`** turns the control into a multi-select list box: the form gets an entry per selected option and `values` in the `mdsInputSelectChange` detail lists them all, while `value` holds the first one, as `select.value` does. **`rows`** sets how many option rows are visible at once, as the `size` of a native `<select>`: above `1` it shows a list box even without `multiple`. A number in `size`, the row count it used to set, still works as `rows` but warns: it is deprecated and goes in the next major.\n- **`defaultValue`** is the initial selection used to seed the value at load (notably for the React wrapper), distinct from the live `value` that reflects the current choice.\n- **`required`** both enforces a non-empty submission and locks the placeholder option so the empty entry cannot be chosen again.\n",
17390
17897
  "2. Examples": "Correct and idiomatic ways to use the `<mds-input-select>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Select with Placeholder\n\nThe canonical form. Slot plain `<option>` elements as direct children. Set `placeholder` to inject a leading empty-value entry that prompts the user before a choice is made.\n\n```html\n<mds-input-select name=\"categoria\" placeholder=\"Seleziona una categoria...\">\n <option value=\"news\">Notizie</option>\n <option value=\"eventi\">Eventi</option>\n <option value=\"avvisi\">Avvisi</option>\n</mds-input-select>\n```\n\n#### Required Select Inside a Form\n\nAdding `required` enforces a non-empty submission - an empty select stops the submit like a native one - and disables the placeholder option once a valid choice exists, so users cannot revert to the empty entry. Place the component inside a `<form>` - it is form-associated and submits natively.\n\n```html\n<form action=\"/salva\" method=\"post\">\n <mds-input-select name=\"regione\" required placeholder=\"Scegli la regione...\">\n <option value=\"lombardia\">Lombardia</option>\n <option value=\"veneto\">Veneto</option>\n <option value=\"toscana\">Toscana</option>\n </mds-input-select>\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Pre-selected Value via `value`\n\nPass `value` to open the component with a specific option already chosen. The matching `<option>` is marked selected automatically. Use `default-value` instead when the initial selection is set once at load and you do not need live two-way binding (notably in the React wrapper).\n\n```html\n<!-- Live controlled value -->\n<mds-input-select name=\"priorita\" value=\"alta\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n\n<!-- Initial seed value for React / SSR -->\n<mds-input-select name=\"priorita\" default-value=\"media\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n```\n\n#### Listening to Value Changes\n\nListen to `mdsInputSelectChange` - do not rely on the native `change` event, which may not bubble out of shadow DOM reliably. The event detail carries the chosen value as a string in `value`, and the values of every selected option in `values`.\n\n```html\n<mds-input-select id=\"stato-pratica\" name=\"stato\" placeholder=\"Seleziona stato...\">\n <option value=\"bozza\">Bozza</option>\n <option value=\"in-lavorazione\">In lavorazione</option>\n <option value=\"chiusa\">Chiusa</option>\n</mds-input-select>\n\n<script>\n document.getElementById('stato-pratica')\n .addEventListener('mdsInputSelectChange', (event) => {\n console.log('Nuovo stato:', event.detail.value);\n });\n</script>\n```\n\n#### Programmatic Value via `setValue()`\n\nUse the `setValue()` async method when you need to change the selection from JavaScript after the component has rendered - for example when a related control resets the form state.\n\n```html\n<mds-input-select id=\"provincia\" name=\"provincia\" placeholder=\"Seleziona provincia...\">\n <option value=\"MI\">Milano</option>\n <option value=\"RM\">Roma</option>\n <option value=\"TO\">Torino</option>\n</mds-input-select>\n\n<script>\n async function resetSelezione() {\n const el = document.getElementById('provincia');\n await el.setValue('MI');\n }\n</script>\n```\n\n#### Disabled State\n\nSet `disabled` as a boolean attribute to block interaction and remove the value from the submitted form data. A status tip is shown automatically while the component is disabled.\n\n```html\n<mds-input-select name=\"tipo-contratto\" disabled placeholder=\"Non disponibile\">\n <option value=\"td\">Tempo determinato</option>\n <option value=\"ti\">Tempo indeterminato</option>\n</mds-input-select>\n```\n\n#### Multi-select List Box\n\n`multiple` switches the component to a scrollable list that allows zero or more simultaneous selections. Use `rows` to control how many rows are visible without scrolling (`size` sets the height of the field). Mark the options to preselect with `selected`, as in a native `<select multiple>`. The form submits an entry per selected option under `name`, and `values` in the `mdsInputSelectChange` detail lists them all; `value` holds only the first one, as `select.value` does.\n\n```html\n<mds-input-select name=\"competenze\" multiple rows=\"4\">\n <option value=\"js\" selected>JavaScript</option>\n <option value=\"ts\" selected>TypeScript</option>\n <option value=\"css\">CSS</option>\n <option value=\"html\">HTML</option>\n <option value=\"react\">React</option>\n</mds-input-select>\n```\n\n#### Grouped Options via `<optgroup>`\n\nThe default slot also accepts `<optgroup>` elements. Use them to group related options under a visible label.\n\n```html\n<mds-input-select name=\"comune\" placeholder=\"Seleziona comune...\">\n <optgroup label=\"Lombardia\">\n <option value=\"MI\">Milano</option>\n <option value=\"BS\">Brescia</option>\n </optgroup>\n <optgroup label=\"Veneto\">\n <option value=\"VE\">Venezia</option>\n <option value=\"VR\">Verona</option>\n </optgroup>\n</mds-input-select>\n```\n\n#### Variant for Validation Feedback\n\nSet `variant` to one of the status values (`error`, `success`, `warning`, `info`) to communicate the validation outcome visually. Use this after a form submission or inline validation, not as decorative styling.\n\n```html\n<!-- Errore di validazione -->\n<mds-input-select name=\"tipologia\" variant=\"error\" required placeholder=\"Seleziona tipologia...\">\n <option value=\"A\">Tipo A</option>\n <option value=\"B\">Tipo B</option>\n</mds-input-select>\n\n<!-- Selezione valida confermata -->\n<mds-input-select name=\"tipologia\" variant=\"success\" value=\"A\">\n <option value=\"A\">Tipo A</option>\n <option value=\"B\">Tipo B</option>\n</mds-input-select>\n```\n\n#### Styling Customization\n\nCustomize the component only through its public `--mds-input-select-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles ([`agents/color.md`](../../../../agents/color.md)) so dark mode and high-contrast modes continue to work correctly. `--mds-input-select-variant-color-rgb` takes a bare RGB triplet (`var(--magma-<role>)`, no `rgb()`); `--mds-input-select-ring` and `--mds-input-select-shadow` take a box-shadow, its color written as `rgb(var(--magma-<role>))`. `--mds-input-select-ring` is the ring at rest: on hover and focus the select draws its own 3px ring in the variant color, so the focus stays visible whatever the ring at rest, in dark mode and with more contrast too; change its color through `--mds-input-select-variant-color-rgb`.\n\n```css\n.sidebar-filter mds-input-select {\n --mds-input-select-variant-color-rgb: var(--magma-accent-emphasis);\n --mds-input-select-ring: 0 0 0 2px rgb(var(--magma-accent-emphasis) / 0.8);\n}\n```\n",
17391
17898
  "3. Mistakes": "Common incorrect uses of `<mds-input-select>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Slot Non-Option Elements\n\nThe default slot is reserved for `<option>` and `<optgroup>` elements. The component clones slot children into the inner `<select>`; any other element is copied verbatim and makes the native select malformed.\n\n```html\n<!-- INCORRECT -->\n<mds-input-select name=\"categoria\">\n <div class=\"option-group\">\n <span>Notizie</span>\n <span>Eventi</span>\n </div>\n</mds-input-select>\n\n<!-- CORRECT -->\n<mds-input-select name=\"categoria\" placeholder=\"Seleziona...\">\n <option value=\"news\">Notizie</option>\n <option value=\"eventi\">Eventi</option>\n</mds-input-select>\n```\n\n#### Do Not Listen to the Native `change` Event\n\n`<mds-input-select>` wraps a shadow-DOM `<select>`; the native `change` event does not bubble out of shadow DOM reliably. Always listen to the documented `mdsInputSelectChange` custom event instead.\n\n```html\n<!-- INCORRECT -->\n<mds-input-select id=\"sel\" name=\"tipo\"></mds-input-select>\n<script>\n document.getElementById('sel').addEventListener('change', (e) => {\n console.log(e.target.value); // may be undefined or stale\n });\n</script>\n\n<!-- CORRECT -->\n<mds-input-select id=\"sel\" name=\"tipo\"></mds-input-select>\n<script>\n document.getElementById('sel').addEventListener('mdsInputSelectChange', (e) => {\n console.log(e.detail.value);\n });\n</script>\n```\n\n#### Do Not Use `variant` for Decorative Styling\n\n`variant` maps to `ThemeStatusVariantType` (`error`, `success`, `warning`, `info`). It is meant to communicate a validation outcome, not to apply a brand color. Using a status variant to make the component visually match a section's color theme misleads users about the control's validation state.\n\n```html\n<!-- INCORRECT - using 'info' just for a blue accent -->\n<mds-input-select name=\"argomento\" variant=\"info\">\n <option value=\"A\">Argomento A</option>\n</mds-input-select>\n\n<!-- CORRECT - set variant only to reflect real validation state -->\n<mds-input-select name=\"argomento\" variant=\"error\" required placeholder=\"Obbligatorio\">\n <option value=\"A\">Argomento A</option>\n</mds-input-select>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Inner `<select>`\n\nThe supported customization surface is the public `--mds-input-select-*` CSS custom properties and the two shadow parts (`select`, `tip-top`). Targeting internal elements with `>>>` or undocumented selectors couples your code to the implementation and breaks on minor releases.\n\n```css\n/* INCORRECT */\nmds-input-select >>> select {\n font-size: 1rem;\n border: 2px solid red;\n}\n\n/* CORRECT */\nmds-input-select {\n --mds-input-select-ring: 0 0 0 2px rgb(var(--magma-danger-emphasis));\n --mds-input-select-variant-color-rgb: var(--magma-danger-emphasis);\n}\nmds-input-select::part(select) {\n font-size: 1rem;\n}\n```\n\n#### Do Not Set `placeholder` When You Need a Real Default Selection\n\n`placeholder` injects an empty-value leading option that disappears from valid choices once `required` is set. If you want the component to open with a specific option pre-selected, use `value` or `default-value` instead.\n\n```html\n<!-- INCORRECT - a real value supplied as placeholder text -->\n<mds-input-select name=\"priorita\" placeholder=\"Media\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n\n<!-- CORRECT - use value to pre-select a real option -->\n<mds-input-select name=\"priorita\" value=\"media\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n```\n\n#### Do Not Replace with a Raw `<select>`\n\n`<mds-input-select>` provides theming, accessible status tips, form-reset integration, and dark/high-contrast support. Reaching for a plain `<select>` bypasses all of that and breaks visual consistency across themes.\n\n```html\n<!-- INCORRECT -->\n<select name=\"categoria\" class=\"form-select\">\n <option value=\"\">Seleziona...</option>\n <option value=\"A\">Categoria A</option>\n</select>\n\n<!-- CORRECT -->\n<mds-input-select name=\"categoria\" placeholder=\"Seleziona...\">\n <option value=\"A\">Categoria A</option>\n</mds-input-select>\n```\n"
17392
17899
  },
@@ -18647,8 +19154,8 @@
18647
19154
  }
18648
19155
  ],
18649
19156
  "usage": {
18650
- "1. Description": "The `<mds-input-tip>` web component is the floating helper container of the Magma Design System input family: it overlays an input field and carries supplementary content (slotted `mds-input-tip-item` chips: status labels, hints, counters) that slides into place when the field becomes active. It is a presentational compound child positioned against its parent input rather than a standalone control.\n\n#### Semantic Behavior\n\n- **Floating overlay**: The tip floats over the parent input's edge without intercepting interaction (`pointer-events: none`, which `mds-input-tip-item` keeps too).\n- **Active expansion**: Setting `active` slides the tip into its expanded position; clearing it collapses the tip back flush with the input. It does not expand the items: each `mds-input-tip-item` shows its text only when its own `expanded` is set.\n- **Empty collapse**: When the host has no slotted content it is hidden entirely, so an unused tip occupies no space.\n- **Default slot is content**: The single default slot carries the tip's arbitrary children; there are no named slots, events, form association, or focus management of its own.\n\n#### Properties & Visual Configurations\n\n- **`active`** drives the expanded vs. collapsed state and is normally toggled by the parent input in response to focus, not set manually.\n- **`position`** selects which edge of the input the tip anchors to and therefore the direction it expands: `'top'` (default) sits on the top edge of the field, `'bottom'` on the bottom edge.\n",
18651
- "2. Examples": "Correct and idiomatic ways to use the `<mds-input-tip>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n`<mds-input-tip>` is an internal compound child used inside [`mds-input`](../mds-input/AGENTS.md), [`mds-input-date`](../mds-input-date/AGENTS.md), and [`mds-input-select`](../mds-input-select/AGENTS.md). It is not meant for standalone use. The patterns below show what the parent components render internally, which is useful when building a custom input wrapper that needs the same behavior.\n\n#### Status Chips Above the Field (position=\"top\")\n\nPosition the tip above the input with `position=\"top\"` (the default). Slot [`mds-input-tip-item`](../mds-input-tip-item/AGENTS.md) children for each status badge to show. The `active` prop slides the tip into its expanded position when the field is focused; each item shows its label only when its own `expanded` is set, which the parent inputs set together with `active`.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"top\" active>\n <mds-input-tip-item variant=\"required\" expanded></mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" placeholder=\"Campo obbligatorio\" />\n</div>\n```\n\n#### Hint and Counter Below the Field (position=\"bottom\")\n\nUse `position=\"bottom\"` to anchor the tip below the input. This is the canonical placement for inline helper text and character-count feedback.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"bottom\" active>\n <mds-input-tip-item variant=\"text\" expanded>\n Inserisci almeno 8 caratteri\n </mds-input-tip-item>\n <mds-input-tip-item variant=\"count-incomplete\" expanded>\n 3 / 8\n </mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" />\n</div>\n```\n\n#### Toggling the Active State on Focus\n\nDrive `active`, and the `expanded` of the items that should open on focus, from a focus/blur handler to animate the tip in and out. Setting `active` slides the tip; removing it (or leaving it unset) collapses it back flush with the input edge.\n\n```html\n<div style=\"position: relative;\" id=\"wrapper\">\n <mds-input-tip position=\"top\" id=\"tip\">\n <mds-input-tip-item variant=\"required\"></mds-input-tip-item>\n </mds-input-tip>\n <input\n type=\"text\"\n id=\"field\"\n placeholder=\"Nome utente\"\n />\n</div>\n\n<script>\n const field = document.getElementById('field');\n const tip = document.getElementById('tip');\n const item = tip.querySelector('mds-input-tip-item');\n field.addEventListener('focus', () => { tip.active = true; item.expanded = true; });\n field.addEventListener('blur', () => { tip.active = undefined; item.expanded = undefined; });\n</script>\n```\n\n#### Disabled and Read-only State Chips\n\nWhen the parent input is disabled or read-only, pass the matching `variant` to show a system-translated label. The `expanded` prop on the item keeps it permanently visible even without focus.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"top\">\n <mds-input-tip-item variant=\"disabled\" expanded></mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" disabled placeholder=\"Campo disabilitato\" />\n</div>\n```\n\n#### Required-field Success Feedback\n\nSwitch the `<mds-input-tip-item>` variant to `required-success` once the field passes validation. The item renders a checkmark icon instead of the \"obbligatorio\" label.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"top\" active>\n <mds-input-tip-item variant=\"required-success\" expanded></mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" value=\"Valore valido\" />\n</div>\n```\n\n#### Multiple Tip Items in One Container\n\nSlot several `<mds-input-tip-item>` elements inside a single `<mds-input-tip>`. The container lays them out in a row and hides itself automatically when it has no children.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"bottom\" active>\n <mds-input-tip-item variant=\"text\" expanded>\n Solo lettere e numeri\n </mds-input-tip-item>\n <mds-input-tip-item variant=\"count-almost\" expanded>\n 18 / 20\n </mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" />\n</div>\n```\n\n#### CSS Customization\n\nStyle the tip only through its public `--mds-input-tip-background` CSS custom property; its offsets come from `position` and `active`. Set it on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` ([`agents/color.md`](../../../../agents/color.md)) so dark mode keeps working.\n\n```css\n.custom-input-wrapper mds-input-tip {\n --mds-input-tip-background: rgb(var(--magma-surface-inverse));\n}\n```\n",
19157
+ "1. Description": "The `<mds-input-tip>` web component is the floating helper container of the Magma Design System input family: it overlays an input field and carries supplementary content (slotted `mds-input-tip-item` chips: status labels, hints, counters) that slides into place when the field becomes active. It is a presentational compound child positioned against its parent input rather than a standalone control.\n\n#### Semantic Behavior\n\n- **Floating overlay**: The tip floats over the parent input's edge without intercepting interaction (`pointer-events: none`, which `mds-input-tip-item` keeps too).\n- **Active expansion**: Setting `active` slides a bottom tip onto the edge of the input; clearing it collapses the tip back flush with the input. A top tip stays where it stands, on the top border. It does not expand the items: each `mds-input-tip-item` shows its text only when its own `expanded` is set.\n- **On the top border**: A top tip stands on the top border of its field, half outside, so that it never covers the button at the end of the field. It keeps clear of the rounded corner by the radius of the field, which the field passes down to it, plus a margin, and sits on the straight part of the border.\n- **Empty collapse**: When the host has no slotted content it is hidden entirely, so an unused tip occupies no space.\n- **Default slot is content**: The single default slot carries the tip's arbitrary children; there are no named slots, events, form association, or focus management of its own.\n\n#### Properties & Visual Configurations\n\n- **`active`** drives the expanded vs. collapsed state and is normally toggled by the parent input in response to focus, not set manually.\n- **`position`** selects which edge of the input the tip anchors to: `'top'` (default) stands on the top border of the field, half outside, and stays there on focus; `'bottom'` sits inside the bottom edge and slides onto it when `active`.\n",
19158
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-input-tip>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n`<mds-input-tip>` is an internal compound child used inside [`mds-input`](../mds-input/AGENTS.md), [`mds-input-date`](../mds-input-date/AGENTS.md), and [`mds-input-select`](../mds-input-select/AGENTS.md). It is not meant for standalone use. The patterns below show what the parent components render internally, which is useful when building a custom input wrapper that needs the same behavior.\n\n#### Status Chips Above the Field (position=\"top\")\n\nPosition the tip on the top border of the input with `position=\"top\"` (the default), half outside, where it never covers the button at the end of the field. Slot [`mds-input-tip-item`](../mds-input-tip-item/AGENTS.md) children for each status badge to show. The parent inputs pass down the radius of their field, so that the tip keeps clear of its rounded corner. The top tip stays on the border when the field is focused; each item shows its label only when its own `expanded` is set, which the parent inputs set together with `active`.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"top\" active>\n <mds-input-tip-item variant=\"required\" expanded></mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" placeholder=\"Campo obbligatorio\" />\n</div>\n```\n\n#### Hint and Counter Below the Field (position=\"bottom\")\n\nUse `position=\"bottom\"` to anchor the tip below the input. This is the canonical placement for inline helper text and character-count feedback.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"bottom\" active>\n <mds-input-tip-item variant=\"text\" expanded>\n Inserisci almeno 8 caratteri\n </mds-input-tip-item>\n <mds-input-tip-item variant=\"count-incomplete\" expanded>\n 3 / 8\n </mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" />\n</div>\n```\n\n#### Toggling the Active State on Focus\n\nDrive `active`, and the `expanded` of the items that should open on focus, from a focus/blur handler to animate the tip in and out. Setting `active` slides a bottom tip onto the edge of the input, and removing it (or leaving it unset) collapses it back flush with it; a top tip stays on the border, and only its items expand.\n\n```html\n<div style=\"position: relative;\" id=\"wrapper\">\n <mds-input-tip position=\"top\" id=\"tip\">\n <mds-input-tip-item variant=\"required\"></mds-input-tip-item>\n </mds-input-tip>\n <input\n type=\"text\"\n id=\"field\"\n placeholder=\"Nome utente\"\n />\n</div>\n\n<script>\n const field = document.getElementById('field');\n const tip = document.getElementById('tip');\n const item = tip.querySelector('mds-input-tip-item');\n field.addEventListener('focus', () => { tip.active = true; item.expanded = true; });\n field.addEventListener('blur', () => { tip.active = undefined; item.expanded = undefined; });\n</script>\n```\n\n#### Disabled and Read-only State Chips\n\nWhen the parent input is disabled or read-only, pass the matching `variant` to show a system-translated label. The `expanded` prop on the item keeps it permanently visible even without focus.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"top\">\n <mds-input-tip-item variant=\"disabled\" expanded></mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" disabled placeholder=\"Campo disabilitato\" />\n</div>\n```\n\n#### Required-field Success Feedback\n\nSwitch the `<mds-input-tip-item>` variant to `required-success` once the field passes validation. The item renders a checkmark icon instead of the \"obbligatorio\" label.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"top\" active>\n <mds-input-tip-item variant=\"required-success\" expanded></mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" value=\"Valore valido\" />\n</div>\n```\n\n#### Multiple Tip Items in One Container\n\nSlot several `<mds-input-tip-item>` elements inside a single `<mds-input-tip>`. The container lays them out in a row and hides itself automatically when it has no children.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"bottom\" active>\n <mds-input-tip-item variant=\"text\" expanded>\n Solo lettere e numeri\n </mds-input-tip-item>\n <mds-input-tip-item variant=\"count-almost\" expanded>\n 18 / 20\n </mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" />\n</div>\n```\n\n#### CSS Customization\n\nStyle the tip only through its public `--mds-input-tip-background` CSS custom property; its offsets come from `position` and `active`. Set it on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` ([`agents/color.md`](../../../../agents/color.md)) so dark mode keeps working.\n\n```css\n.custom-input-wrapper mds-input-tip {\n --mds-input-tip-background: rgb(var(--magma-surface-inverse));\n}\n```\n",
18652
19159
  "3. Mistakes": "Common incorrect uses of `<mds-input-tip>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use mds-input-tip as a Standalone Tooltip\n\n`<mds-input-tip>` is an internal compound child of [`mds-input`](../mds-input/AGENTS.md), [`mds-input-date`](../mds-input-date/AGENTS.md), and [`mds-input-select`](../mds-input-select/AGENTS.md). It relies on absolute positioning inside a relatively-positioned input shell; outside that context it has no anchor. Use [`mds-tooltip`](../mds-tooltip/AGENTS.md) or [`mds-help`](../mds-help/AGENTS.md) for standalone floating hints.\n\n```html\n<!-- INCORRECT -->\n<mds-input-tip active>\n <mds-input-tip-item variant=\"text\">Suggerimento generico</mds-input-tip-item>\n</mds-input-tip>\n\n<!-- CORRECT -->\n<mds-help>Suggerimento generico</mds-help>\n```\n\n#### Do Not Put Plain Text Directly in the Default Slot\n\nThe default slot of `<mds-input-tip>` accepts only [`mds-input-tip-item`](../mds-input-tip-item/AGENTS.md) elements. Plain text nodes are not styled or accessible. Use `<mds-input-tip-item variant=\"text\">` to carry freeform hint copy.\n\n```html\n<!-- INCORRECT -->\n<mds-input-tip position=\"bottom\" active>\n Inserisci la tua email aziendale\n</mds-input-tip>\n\n<!-- CORRECT -->\n<mds-input-tip position=\"bottom\" active>\n <mds-input-tip-item variant=\"text\">\n Inserisci la tua email aziendale\n </mds-input-tip-item>\n</mds-input-tip>\n```\n\n#### Do Not Set active=\"false\" to Collapse the Tip\n\n`active` is a boolean attribute: remove it (or set the prop to `undefined`) to collapse. A string value is fragile: `\"false\"` is read as `false` on this component, but the attribute stays on the element until the component renders (attribute selectors and scripts reading it see it set). Never write a boolean as a string.\n\n```html\n<!-- INCORRECT -->\n<mds-input-tip position=\"top\" active=\"false\">\n <mds-input-tip-item variant=\"required\"></mds-input-tip-item>\n</mds-input-tip>\n\n<!-- CORRECT -->\n<mds-input-tip position=\"top\">\n <mds-input-tip-item variant=\"required\"></mds-input-tip-item>\n</mds-input-tip>\n```\n\n#### Do Not Use an Undocumented position Value\n\n`position` accepts only `\"top\"` and `\"bottom\"`. Any other value (e.g. `\"left\"`, `\"right\"`) is not typed and has no matching CSS rule; the tip falls back to the initial-value behavior silently.\n\n```html\n<!-- INCORRECT -->\n<mds-input-tip position=\"left\" active>\n <mds-input-tip-item variant=\"text\">Aiuto</mds-input-tip-item>\n</mds-input-tip>\n\n<!-- CORRECT -->\n<mds-input-tip position=\"bottom\" active>\n <mds-input-tip-item variant=\"text\">Aiuto</mds-input-tip-item>\n</mds-input-tip>\n```\n\n#### Do Not Slot Non-tip-item Elements for Custom Styles\n\nSlotting arbitrary HTML or other Magma components (e.g. `<mds-badge>`, `<span>`) bypasses the item's own layout, color tokens, and border-radius joining logic. Always wrap content in `<mds-input-tip-item>`.\n\n```html\n<!-- INCORRECT -->\n<mds-input-tip position=\"bottom\" active>\n <span style=\"color: red;\">Testo personalizzato</span>\n</mds-input-tip>\n\n<!-- CORRECT -->\n<mds-input-tip position=\"bottom\" active>\n <mds-input-tip-item variant=\"text\">Testo personalizzato</mds-input-tip-item>\n</mds-input-tip>\n```\n\n#### Do Not Override Positioning via Inline Styles\n\nThe tip is absolutely positioned by its own CSS, driven by its `position` and `active` props. Setting `position`, `top`, `left`, or `right` inline breaks the animation transform and the active-state offset calculation.\n\n```css\n/* INCORRECT */\nmds-input-tip {\n position: relative;\n top: 10px;\n}\n```\n\n```html\n<!-- CORRECT -->\n<div style=\"position: relative;\">\n <mds-input-tip position=\"bottom\" active>\n <mds-input-tip-item variant=\"text\" expanded>Inserisci almeno 8 caratteri</mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" />\n</div>\n```\n"
18653
19160
  },
18654
19161
  "props": [
@@ -18663,7 +19170,7 @@
18663
19170
  "mutable": false,
18664
19171
  "attr": "active",
18665
19172
  "reflectToAttr": true,
18666
- "docs": "Moves the tip onto the edge of the input, as the parent input does while it has the focus.\nIt does not expand the items: each `mds-input-tip-item` opens on its own `expanded`",
19173
+ "docs": "Moves the bottom tip onto the edge of the input, as the parent input does while it has the\nfocus; the top tip stays on the border of the field. It does not expand the items: each\n`mds-input-tip-item` opens on its own `expanded`",
18667
19174
  "docsTags": [
18668
19175
  {
18669
19176
  "name": "default",
@@ -18702,7 +19209,7 @@
18702
19209
  "mutable": false,
18703
19210
  "attr": "position",
18704
19211
  "reflectToAttr": true,
18705
- "docs": "Specifies the position of the element relative to its container",
19212
+ "docs": "Specifies the position of the element relative to its container: `top` stands on the top\nborder of the field, half outside, clear of its corner by the radius the field passes down plus\na margin; `bottom` sits inside the bottom edge",
18706
19213
  "docsTags": [
18707
19214
  {
18708
19215
  "name": "default",
@@ -18736,7 +19243,7 @@
18736
19243
  {
18737
19244
  "name": "--mds-input-tip-active-translate",
18738
19245
  "annotation": "prop",
18739
- "docs": "Transform applied to the tip when active",
19246
+ "docs": "Transform applied to the bottom tip when active",
18740
19247
  "visibility": "internal"
18741
19248
  },
18742
19249
  {
@@ -18745,22 +19252,28 @@
18745
19252
  "docs": "Background color of the input tip",
18746
19253
  "visibility": "public"
18747
19254
  },
19255
+ {
19256
+ "name": "--mds-input-tip-field-radius",
19257
+ "annotation": "prop",
19258
+ "docs": "The corner radius of the field the tip stands on: the top tip keeps clear of the corner by it, plus a margin",
19259
+ "visibility": "internal"
19260
+ },
18748
19261
  {
18749
19262
  "name": "--mds-input-tip-horizontal-offset",
18750
19263
  "annotation": "prop",
18751
- "docs": "Default horizontal offset of the input tip",
19264
+ "docs": "Default horizontal offset of the bottom tip",
18752
19265
  "visibility": "internal"
18753
19266
  },
18754
19267
  {
18755
19268
  "name": "--mds-input-tip-horizontal-offset-focused",
18756
19269
  "annotation": "prop",
18757
- "docs": "Horizontal offset applied when the input is focused",
19270
+ "docs": "Horizontal offset of the bottom tip when the input is focused",
18758
19271
  "visibility": "internal"
18759
19272
  },
18760
19273
  {
18761
19274
  "name": "--mds-input-tip-vertical-offset",
18762
19275
  "annotation": "prop",
18763
- "docs": "Vertical offset of the input tip",
19276
+ "docs": "Vertical offset of the bottom tip",
18764
19277
  "visibility": "internal"
18765
19278
  }
18766
19279
  ],
@@ -19370,8 +19883,8 @@
19370
19883
  "mds-file-preview"
19371
19884
  ],
19372
19885
  "mds-button": [
19373
- "mds-spinner",
19374
19886
  "mds-icon",
19887
+ "mds-spinner",
19375
19888
  "mds-text"
19376
19889
  ],
19377
19890
  "mds-progress": [
@@ -19635,8 +20148,8 @@
19635
20148
  "mds-tooltip"
19636
20149
  ],
19637
20150
  "mds-button": [
19638
- "mds-spinner",
19639
20151
  "mds-icon",
20152
+ "mds-spinner",
19640
20153
  "mds-text"
19641
20154
  ],
19642
20155
  "mds-tooltip": [
@@ -20735,8 +21248,8 @@
20735
21248
  "mds-button"
20736
21249
  ],
20737
21250
  "mds-button": [
20738
- "mds-spinner",
20739
21251
  "mds-icon",
21252
+ "mds-spinner",
20740
21253
  "mds-text"
20741
21254
  ]
20742
21255
  },
@@ -21591,8 +22104,8 @@
21591
22104
  "mds-button"
21592
22105
  ],
21593
22106
  "mds-button": [
21594
- "mds-spinner",
21595
22107
  "mds-icon",
22108
+ "mds-spinner",
21596
22109
  "mds-text"
21597
22110
  ]
21598
22111
  },
@@ -21639,8 +22152,8 @@
21639
22152
  }
21640
22153
  ],
21641
22154
  "usage": {
21642
- "1. Description": "The `<mds-modal>` web component is the Magma Design System overlay container for dialogs, presenting content in a windowed surface layered above the page with an optional backdrop. It is the system equivalent of the native `<dialog>` element, adding managed open/close animations, body scroll locking, positioning, and a built-in close affordance.\n\n#### Semantic Behavior\n\n- **Open state**: Visibility is driven by the `opened` prop. Setting it `true` runs the intro animation and emits `mdsModalOpen`; clearing it runs the outro animation and emits `mdsModalClose`.\n- **Programmatic close**: Exposes an async `close()` method that dismisses the modal regardless of `interaction`, mirroring the close-button action.\n- **Show/hide events**: `mdsModalShow` fires when the intro finishes (fully visible) and `mdsModalHide` when the outro finishes (fully hidden), the latter being the safe point to detach the modal to reclaim memory.\n- **Backdrop dismissal**: With `interaction=\"relaxed\"` (default) a click on the backdrop or `Esc` closes the modal; with `interaction=\"strict\"` both are ignored, and the touch swipe too (below): only the close button or `close()` can dismiss it.\n- **Body scroll lock**: When `overflow=\"auto\"` the component locks body scroll while open and restores it on close.\n- **Touch dismissal**: On touch devices a horizontal swipe past a threshold closes a `relaxed` modal, respecting the swipe direction implied by edge `position` values.\n- **Slot-driven layout**: With no `window` slot, the default slot renders centered content framed by optional `top` (header) and `bottom` (footer) slots, and a close button is rendered automatically, icon-only and named in the page language (the `lang` of `<html>`) (\"Close\"). Slotting a `window` element suppresses the built-in chrome and close button so the consumer supplies the entire surface.\n- **Width of a slotted window**: The `window` element stops at the width of a dialog, `--magma-width-dialog` (the column of a form plus its inset, 580px at 16px: `widths/dialog` of the design language), and shrinks with a narrower screen, its margin around it. A class on the element wins over it, for a bespoke surface.\n- **Close button placement**: The built-in close button sits on the backdrop, in a strip the window always leaves free, so a `strict` modal can be closed whatever its content. `left` and `right` leave it at their side at every width.\n- **Narrow screens**: At a viewport of 480px or less a window that would fill the screen (`center` and the four corners) leaves a strip of backdrop at the top, where the close button shows, as `left` and `right` leave one at their side; `top` and `bottom` stay as tall as their content but never taller than the screen less that strip, which stays on their free side with the close button at its edge (top right for `bottom`, bottom right for `top`).\n- **Wide screens**: Above 480px every window leaves a strip of backdrop at its side, with the close button at its top: `center`, `top` and `bottom` one on each side, the button at the top right; the corners one on the side away from their own, the button there.\n\n#### Properties & Visual Configurations\n\nThis component does not use the shared `variant` / `tone` ladders; its configuration is structural and motion-oriented.\n\n#### Other behavioral props\n\n- **`position`** sets where the window animates from and rests, from `'center'` to edge and corner anchors (`'top'`, `'bottom-left'`, etc.); edge positions also define the valid swipe-to-dismiss direction.\n- **`animation`** selects the motion style of the window: `'slide'` (default), `'3d'`, or `'custom'` (driven entirely by CSS custom properties).\n- **`interaction`** governs how forgiving dismissal is - `'relaxed'` allows backdrop clicks, `'strict'` requires the close button.\n- **`overflow`** chooses whether the component manages body scroll locking (`'auto'`) or leaves it to the consumer (`'manual'`).\n- **`hideBackdrop`** removes the dimmed overlay behind the window (shown by default).\n",
21643
- "2. Examples": "Correct and idiomatic ways to use the `<mds-modal>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Modal with Inline Content\n\nThe simplest form: toggle `opened` from JavaScript to show the dialog. The built-in close button and backdrop dismiss the modal automatically with `interaction=\"relaxed\"` (default). React to the `mdsModalClose` event to sync your state.\n\n```html\n<mds-button id=\"btn-apri\">Apri dialogo</mds-button>\n\n<mds-modal id=\"dialogo\">\n <div class=\"p-400\">\n <mds-text>Sei sicuro di voler continuare?</mds-text>\n </div>\n</mds-modal>\n\n<script>\n const btn = document.getElementById('btn-apri');\n const modal = document.getElementById('dialogo');\n btn.addEventListener('click', () => { modal.opened = true; });\n modal.addEventListener('mdsModalClose', () => { modal.opened = undefined; });\n</script>\n```\n\n#### Fixed Header and Footer via `top` / `bottom` Slots\n\nUse the `top` slot for a sticky header and the `bottom` slot for a sticky footer (e.g. action buttons). The default slot renders scrollable body content between them.\n\n```html\n<mds-modal id=\"modifica-utente\" position=\"right\">\n <header slot=\"top\" class=\"p-400 bg-surface-overlay shadow-ring-weak\">\n <mds-text typography=\"h5\">Modifica utente</mds-text>\n </header>\n\n <div class=\"p-400 grid gap-400\">\n <mds-input-field label=\"Nome\">\n <mds-input name=\"nome\"></mds-input>\n </mds-input-field>\n <mds-input-field label=\"Cognome\">\n <mds-input name=\"cognome\"></mds-input>\n </mds-input-field>\n </div>\n\n <footer slot=\"bottom\" class=\"p-400 flex gap-300 justify-end bg-surface-overlay shadow-ring-weak\">\n <mds-button variant=\"dark\" tone=\"outline\" id=\"btn-annulla\">Annulla</mds-button>\n <mds-button variant=\"primary\" tone=\"strong\" id=\"btn-salva\">Salva</mds-button>\n </footer>\n</mds-modal>\n```\n\n#### Edge and Corner Positions\n\n`position` anchors the window to an edge or corner and drives the slide-in direction. Use `right` or `left` for side panels, `bottom` for mobile drawers.\n\n```html\n<!-- Side panel from the right (default in most app shells) -->\n<mds-modal id=\"pannello-laterale\" position=\"right\">\n <div class=\"p-400\">\n <mds-text>Dettagli del documento</mds-text>\n </div>\n</mds-modal>\n\n<!-- Drawer from the bottom (mobile) -->\n<mds-modal id=\"drawer-mobile\" position=\"bottom\">\n <div class=\"p-400\">\n <mds-text>Azioni disponibili</mds-text>\n </div>\n</mds-modal>\n```\n\n#### Strict Interaction Mode\n\nSet `interaction=\"strict\"` when the user must explicitly confirm or cancel before the dialog closes - for example, a form with unsaved changes. Backdrop clicks, `Esc` and touch swipes are ignored; only the close button or the `close()` method can dismiss the modal.\n\n```html\n<mds-modal id=\"conferma-elimina\" interaction=\"strict\">\n <div class=\"p-400 grid gap-400\">\n <mds-text typography=\"h5\">Eliminare il documento?</mds-text>\n <mds-text>Questa operazione non e' reversibile.</mds-text>\n <div class=\"flex gap-300 justify-end\">\n <mds-button variant=\"dark\" tone=\"outline\" id=\"btn-no\">Annulla</mds-button>\n <mds-button variant=\"error\" tone=\"strong\" id=\"btn-si\">Elimina</mds-button>\n </div>\n </div>\n</mds-modal>\n\n<script>\n document.getElementById('btn-no').addEventListener('click', () => {\n document.getElementById('conferma-elimina').close();\n });\n</script>\n```\n\n#### Programmatic Close via `close()` Method\n\nCall the async `close()` method from JavaScript when you need to dismiss the modal from outside its UI - for example, after a successful async operation.\n\n```html\n<mds-modal id=\"salvataggio\">\n <div class=\"p-400\">\n <mds-text>Salvataggio in corso...</mds-text>\n </div>\n</mds-modal>\n\n<script>\n async function salva() {\n const modal = document.getElementById('salvataggio');\n modal.opened = true;\n await salvaRisorsa();\n await modal.close();\n }\n</script>\n```\n\n#### Listening to Animation Events\n\n`mdsModalShow` fires when the intro animation completes (the modal is fully visible). Use it to focus the first interactive element. `mdsModalHide` fires when the outro animation completes; use it to detach the element or reset content.\n\n```html\n<mds-modal id=\"modal-focus\" position=\"right\">\n <div class=\"p-400\">\n <mds-input-field label=\"Cerca\">\n <mds-input id=\"input-ricerca\" name=\"ricerca\"></mds-input>\n </mds-input-field>\n </div>\n</mds-modal>\n\n<script>\n const modal = document.getElementById('modal-focus');\n const input = document.getElementById('input-ricerca');\n\n modal.addEventListener('mdsModalShow', () => {\n input.setFocus();\n });\n modal.addEventListener('mdsModalHide', () => {\n // safe point to detach or reset content\n modal.opened = undefined;\n });\n</script>\n```\n\n#### Custom Animation Styles\n\n`animation` selects the motion style. `'slide'` (default) translates from the entry edge; `'3d'` adds a perspective tilt; `'custom'` delegates entirely to the CSS custom properties `--mds-modal-custom-closed-transform` and `--mds-modal-custom-window-distance`.\n\n```html\n<!-- 3D perspective tilt animation -->\n<mds-modal id=\"modal-3d\" animation=\"3d\" position=\"center\">\n <div class=\"p-400\">\n <mds-text>Animazione 3D</mds-text>\n </div>\n</mds-modal>\n\n<!-- Custom animation driven by CSS vars -->\n<mds-modal id=\"modal-custom\" animation=\"custom\" position=\"center\">\n <div class=\"p-400\">\n <mds-text>Animazione personalizzata</mds-text>\n </div>\n</mds-modal>\n```\n\n#### The Window of a Dialog via the `window` Slot\n\nSlot an element with `slot=\"window\"` to replace the built-in chrome (the window surface and the close button). A dialog slots an [`mds-banner`](../mds-banner/AGENTS.md) `variant=\"light\"` `tone=\"box\"` `dismissible`: its own close button closes the modal. The slotted element gets no `role` of its own: the `<dialog>` the component renders is already the dialog, named by the `aria-label` of the host. The actions follow the rules of a dialog: the secondary one `dark` `outline`, the main one last.\n\nThe window stops at the width of a dialog, the column of a form plus its inset (`--magma-width-dialog`, 580px at 16px, `widths/dialog` of the design language), and shrinks with a narrower screen. Write no width on it: a form keeps in the window the shape it has in the page.\n\n```html\n<mds-modal id=\"modal-banner\" aria-label=\"Azione richiesta\">\n <mds-banner slot=\"window\" variant=\"light\" tone=\"box\" dismissible headline=\"Azione richiesta\">\n <mds-text typography=\"detail\">Conferma la tua identita' per procedere.</mds-text>\n <mds-button slot=\"action\" variant=\"dark\" tone=\"outline\">Annulla</mds-button>\n <mds-button slot=\"action\" variant=\"primary\" tone=\"strong\">Conferma</mds-button>\n </mds-banner>\n</mds-modal>\n```\n\nA bespoke surface, such as a banner as wide as the screen, writes its own width with a class: from the light DOM it wins over the width of a dialog.\n\n```html\n<mds-modal id=\"modal-novita\" aria-label=\"Novita'\">\n <mds-banner slot=\"window\" class=\"max-w-none\" variant=\"light\" tone=\"box\" dismissible headline=\"Novita'\">\n <mds-text typography=\"detail\">Da oggi puoi firmare i documenti dall'app.</mds-text>\n </mds-banner>\n</mds-modal>\n```\n\n#### Disabling the Backdrop\n\nAdd `hide-backdrop` to render the modal without the dimmed overlay - useful for non-blocking side panels that coexist with interactive page content.\n\n```html\n<mds-modal id=\"pannello-info\" position=\"right\" hide-backdrop>\n <div class=\"p-400\">\n <mds-text>Informazioni contestuali</mds-text>\n </div>\n</mds-modal>\n```\n\n```javascript\n// Remove the backdrop from JavaScript (it applies from the next opening)\ndocument.getElementById('pannello-info').hideBackdrop = true;\n```\n\n#### CSS Customization\n\nSize and place the window only through the public `--mds-modal-*` CSS custom properties. Set them on the host element; the window takes its background, radius and shadow from the component. They size the built-in window: a slotted window takes the width of a dialog, or the one its class gives it.\n\n```css\n/* Narrow center modal */\n#modal-card {\n --mds-modal-window-distance: calc(var(--spacing) * 600);\n --mds-modal-window-overflow: hidden;\n --mds-modal-window-max-width: 480px;\n}\n\n/* Full-width drawer */\n#drawer-bottom {\n --mds-modal-window-max-width: 100%;\n --mds-modal-window-min-width: 100%;\n}\n```\n",
22155
+ "1. Description": "The `<mds-modal>` web component is the Magma Design System overlay container for dialogs, presenting content in a windowed surface layered above the page with an optional backdrop. It is the system equivalent of the native `<dialog>` element, adding managed open/close animations, body scroll locking, positioning, and a built-in close affordance.\n\n#### Semantic Behavior\n\n- **Open state**: Visibility is driven by the `opened` prop. Setting it `true` runs the intro animation and emits `mdsModalOpen`; clearing it runs the outro animation and emits `mdsModalClose`.\n- **Programmatic close**: Exposes an async `close()` method that dismisses the modal regardless of `interaction`, mirroring the close-button action.\n- **Show/hide events**: `mdsModalShow` fires when the intro finishes (fully visible) and `mdsModalHide` when the outro finishes (fully hidden), the latter being the safe point to detach the modal to reclaim memory.\n- **Backdrop dismissal**: With `interaction=\"relaxed\"` (default) a click on the backdrop or `Esc` closes the modal. The click counts when it is pressed and released on the backdrop once the window has stopped: a text selection dragged out of a field, a drag from the backdrop into the window or a click while the window is still coming in leave the modal open. With `interaction=\"strict\"` both are ignored, and the touch swipe too (below): only the close button or `close()` can dismiss it.\n- **Body scroll lock**: When `overflow=\"auto\"` the component locks body scroll while open and restores it on close.\n- **Touch dismissal**: On touch devices a horizontal swipe past a threshold closes a `relaxed` modal, respecting the swipe direction implied by edge `position` values.\n- **Slot-driven layout**: With no `window` slot, the default slot renders centered content framed by optional `top` (header) and `bottom` (footer) slots, and a close button is rendered automatically, icon-only and named in the page language (the `lang` of `<html>`) (\"Close\"). Slotting a `window` element suppresses the built-in chrome and close button so the consumer supplies the entire surface.\n- **Title of a banner window**: An `mds-banner` slotted as the `window` draws its `headline` in `h5`, the title of a dialog (`titles/dialog` of the design language), above the `h6` of the parts and the groups of fields the dialog holds; in the page the banner keeps `h6`. The headline is hidden from screen readers: the dialog takes its name from `aria-label` on the host.\n- **Width of a slotted window**: The `window` element stops at the width of a dialog, `--magma-width-dialog` (the column of a form plus its inset, 580px at 16px: `widths/dialog` of the design language), and shrinks with a narrower screen, its margin around it. A class on the element wins over it, for a bespoke surface.\n- **Close button placement**: The built-in close button sits on the backdrop, in a strip the window always leaves free, so a `strict` modal can be closed whatever its content. `left` and `right` leave it at their side at every width.\n- **Narrow screens**: At a viewport of 480px or less a window that would fill the screen (`center` and the four corners) leaves a strip of backdrop at the top, where the close button shows, as `left` and `right` leave one at their side; `top` and `bottom` stay as tall as their content but never taller than the screen less that strip, which stays on their free side with the close button at its edge (top right for `bottom`, bottom right for `top`).\n- **Wide screens**: Above 480px every window leaves a strip of backdrop at its side, with the close button at its top: `center`, `top` and `bottom` one on each side, the button at the top right; the corners one on the side away from their own, the button there.\n\n#### Properties & Visual Configurations\n\nThis component does not use the shared `variant` / `tone` ladders; its configuration is structural and motion-oriented.\n\n#### Other behavioral props\n\n- **`position`** sets where the window animates from and rests, from `'center'` to edge and corner anchors (`'top'`, `'bottom-left'`, etc.); edge positions also define the valid swipe-to-dismiss direction.\n- **`animation`** selects the motion style of the window: `'slide'` (default), `'3d'`, or `'custom'` (driven entirely by CSS custom properties).\n- **`interaction`** governs how forgiving dismissal is - `'relaxed'` allows backdrop clicks, `'strict'` requires the close button.\n- **`overflow`** chooses whether the component manages body scroll locking (`'auto'`) or leaves it to the consumer (`'manual'`).\n- **`hideBackdrop`** removes the dimmed overlay behind the window (shown by default).\n",
22156
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-modal>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Modal with Inline Content\n\nThe simplest form: toggle `opened` from JavaScript to show the dialog. The built-in close button and backdrop dismiss the modal automatically with `interaction=\"relaxed\"` (default). React to the `mdsModalClose` event to sync your state.\n\n```html\n<mds-button id=\"btn-apri\">Apri dialogo</mds-button>\n\n<mds-modal id=\"dialogo\">\n <div class=\"p-400\">\n <mds-text>Sei sicuro di voler continuare?</mds-text>\n </div>\n</mds-modal>\n\n<script>\n const btn = document.getElementById('btn-apri');\n const modal = document.getElementById('dialogo');\n btn.addEventListener('click', () => { modal.opened = true; });\n modal.addEventListener('mdsModalClose', () => { modal.opened = undefined; });\n</script>\n```\n\n#### Fixed Header and Footer via `top` / `bottom` Slots\n\nUse the `top` slot for a sticky header and the `bottom` slot for a sticky footer (e.g. action buttons). The default slot renders scrollable body content between them.\n\n```html\n<mds-modal id=\"modifica-utente\" position=\"right\">\n <header slot=\"top\" class=\"p-400 bg-surface-overlay shadow-ring-weak\">\n <mds-text typography=\"h5\">Modifica utente</mds-text>\n </header>\n\n <div class=\"p-400 grid gap-400\">\n <mds-input-field label=\"Nome\">\n <mds-input name=\"nome\"></mds-input>\n </mds-input-field>\n <mds-input-field label=\"Cognome\">\n <mds-input name=\"cognome\"></mds-input>\n </mds-input-field>\n </div>\n\n <footer slot=\"bottom\" class=\"p-400 flex gap-300 justify-end bg-surface-overlay shadow-ring-weak\">\n <mds-button variant=\"dark\" tone=\"outline\" id=\"btn-annulla\">Annulla</mds-button>\n <mds-button variant=\"primary\" tone=\"strong\" id=\"btn-salva\">Salva</mds-button>\n </footer>\n</mds-modal>\n```\n\n#### Edge and Corner Positions\n\n`position` anchors the window to an edge or corner and drives the slide-in direction. Use `right` or `left` for side panels, `bottom` for mobile drawers.\n\n```html\n<!-- Side panel from the right (default in most app shells) -->\n<mds-modal id=\"pannello-laterale\" position=\"right\">\n <div class=\"p-400\">\n <mds-text>Dettagli del documento</mds-text>\n </div>\n</mds-modal>\n\n<!-- Drawer from the bottom (mobile) -->\n<mds-modal id=\"drawer-mobile\" position=\"bottom\">\n <div class=\"p-400\">\n <mds-text>Azioni disponibili</mds-text>\n </div>\n</mds-modal>\n```\n\n#### Strict Interaction Mode\n\nSet `interaction=\"strict\"` when the user must explicitly confirm or cancel before the dialog closes - for example, a form with unsaved changes. Backdrop clicks, `Esc` and touch swipes are ignored; only the close button or the `close()` method can dismiss the modal.\n\n```html\n<mds-modal id=\"conferma-elimina\" interaction=\"strict\">\n <div class=\"p-400 grid gap-400\">\n <mds-text typography=\"h5\">Eliminare il documento?</mds-text>\n <mds-text>Questa operazione non e' reversibile.</mds-text>\n <div class=\"flex gap-300 justify-end\">\n <mds-button variant=\"dark\" tone=\"outline\" id=\"btn-no\">Annulla</mds-button>\n <mds-button variant=\"error\" tone=\"strong\" id=\"btn-si\">Elimina</mds-button>\n </div>\n </div>\n</mds-modal>\n\n<script>\n document.getElementById('btn-no').addEventListener('click', () => {\n document.getElementById('conferma-elimina').close();\n });\n</script>\n```\n\n#### Programmatic Close via `close()` Method\n\nCall the async `close()` method from JavaScript when you need to dismiss the modal from outside its UI - for example, after a successful async operation.\n\n```html\n<mds-modal id=\"salvataggio\">\n <div class=\"p-400\">\n <mds-text>Salvataggio in corso...</mds-text>\n </div>\n</mds-modal>\n\n<script>\n async function salva() {\n const modal = document.getElementById('salvataggio');\n modal.opened = true;\n await salvaRisorsa();\n await modal.close();\n }\n</script>\n```\n\n#### Listening to Animation Events\n\n`mdsModalShow` fires when the intro animation completes (the modal is fully visible). Use it to focus the first interactive element. `mdsModalHide` fires when the outro animation completes; use it to detach the element or reset content.\n\n```html\n<mds-modal id=\"modal-focus\" position=\"right\">\n <div class=\"p-400\">\n <mds-input-field label=\"Cerca\">\n <mds-input id=\"input-ricerca\" name=\"ricerca\"></mds-input>\n </mds-input-field>\n </div>\n</mds-modal>\n\n<script>\n const modal = document.getElementById('modal-focus');\n const input = document.getElementById('input-ricerca');\n\n modal.addEventListener('mdsModalShow', () => {\n input.setFocus();\n });\n modal.addEventListener('mdsModalHide', () => {\n // safe point to detach or reset content\n modal.opened = undefined;\n });\n</script>\n```\n\n#### Custom Animation Styles\n\n`animation` selects the motion style. `'slide'` (default) translates from the entry edge; `'3d'` adds a perspective tilt; `'custom'` delegates entirely to the CSS custom properties `--mds-modal-custom-closed-transform` and `--mds-modal-custom-window-distance`.\n\n```html\n<!-- 3D perspective tilt animation -->\n<mds-modal id=\"modal-3d\" animation=\"3d\" position=\"center\">\n <div class=\"p-400\">\n <mds-text>Animazione 3D</mds-text>\n </div>\n</mds-modal>\n\n<!-- Custom animation driven by CSS vars -->\n<mds-modal id=\"modal-custom\" animation=\"custom\" position=\"center\">\n <div class=\"p-400\">\n <mds-text>Animazione personalizzata</mds-text>\n </div>\n</mds-modal>\n```\n\n#### The Window of a Dialog via the `window` Slot\n\nSlot an element with `slot=\"window\"` to replace the built-in chrome (the window surface and the close button). A dialog slots an [`mds-banner`](../mds-banner/AGENTS.md) `variant=\"light\"` `tone=\"box\"` `dismissible`: its own close button closes the modal. The slotted element gets no `role` of its own: the `<dialog>` the component renders is already the dialog, named by the `aria-label` of the host. The actions follow the rules of a dialog: the secondary one `dark` `outline`, the main one last.\n\nThe window stops at the width of a dialog, the column of a form plus its inset (`--magma-width-dialog`, 580px at 16px, `widths/dialog` of the design language), and shrinks with a narrower screen. Write no width on it: a form keeps in the window the shape it has in the page.\n\nThe headline of the banner is the title of the dialog, in `h5` (`titles/dialog`): the banner takes the style from its place, so write no `typography` on it. It is hidden from screen readers, so the `aria-label` of the host carries the same text.\n\n```html\n<mds-modal id=\"modal-banner\" aria-label=\"Azione richiesta\">\n <mds-banner slot=\"window\" variant=\"light\" tone=\"box\" dismissible headline=\"Azione richiesta\">\n <mds-text typography=\"detail\">Conferma la tua identita' per procedere.</mds-text>\n <mds-button slot=\"action\" variant=\"dark\" tone=\"outline\">Annulla</mds-button>\n <mds-button slot=\"action\" variant=\"primary\" tone=\"strong\">Conferma</mds-button>\n </mds-banner>\n</mds-modal>\n```\n\nA bespoke surface, such as a banner as wide as the screen, writes its own width with a class: from the light DOM it wins over the width of a dialog.\n\n```html\n<mds-modal id=\"modal-novita\" aria-label=\"Novita'\">\n <mds-banner slot=\"window\" class=\"max-w-none\" variant=\"light\" tone=\"box\" dismissible headline=\"Novita'\">\n <mds-text typography=\"detail\">Da oggi puoi firmare i documenti dall'app.</mds-text>\n </mds-banner>\n</mds-modal>\n```\n\n#### Disabling the Backdrop\n\nAdd `hide-backdrop` to render the modal without the dimmed overlay - useful for non-blocking side panels that coexist with interactive page content.\n\n```html\n<mds-modal id=\"pannello-info\" position=\"right\" hide-backdrop>\n <div class=\"p-400\">\n <mds-text>Informazioni contestuali</mds-text>\n </div>\n</mds-modal>\n```\n\n```javascript\n// Remove the backdrop from JavaScript (it applies from the next opening)\ndocument.getElementById('pannello-info').hideBackdrop = true;\n```\n\n#### CSS Customization\n\nSize and place the window only through the public `--mds-modal-*` CSS custom properties. Set them on the host element; the window takes its background, radius and shadow from the component. They size the built-in window: a slotted window takes the width of a dialog, or the one its class gives it.\n\n```css\n/* Narrow center modal */\n#modal-card {\n --mds-modal-window-distance: calc(var(--spacing) * 600);\n --mds-modal-window-overflow: hidden;\n --mds-modal-window-max-width: 480px;\n}\n\n/* Full-width drawer */\n#drawer-bottom {\n --mds-modal-window-max-width: 100%;\n --mds-modal-window-min-width: 100%;\n}\n```\n",
21644
22157
  "3. Mistakes": "Common incorrect uses of `<mds-modal>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Set `opened=\"false\"` to Close the Modal\n\nA false boolean is an absent attribute ([`agents/conventions.md`](../../../../agents/conventions.md)). The runtime does parse the string `\"false\"` as `false`, so the modal stays closed, but the attribute is still on the element until the first render, so `[opened]` attribute selectors and any code that reads the attribute see it set. Remove the attribute; from JavaScript set the prop to `undefined` (`false` works too: the component turns it into `undefined`).\n\n```html\n<!-- INCORRECT -->\n<mds-modal id=\"dialogo\" opened=\"false\"></mds-modal>\n\n<!-- CORRECT -->\n<mds-modal id=\"dialogo\"></mds-modal>\n```\n\n#### Do Not Put Content in the `window` Slot Without Replacing the Entire Chrome\n\nThe `window` slot completely bypasses the built-in surface, header/footer regions, and close button. Do not use it to add a header element while expecting the default content area and close button to still render - they will not.\n\n```html\n<!-- INCORRECT: only the slotted header renders; default slot and close button are suppressed -->\n<mds-modal id=\"modal\">\n <header slot=\"window\" class=\"p-400\">Titolo</header>\n <div>Contenuto del dialogo</div>\n</mds-modal>\n\n<!-- CORRECT: use slot=\"top\" for a sticky header, default slot for body -->\n<mds-modal id=\"modal\">\n <header slot=\"top\" class=\"p-400 bg-surface-overlay\">Titolo</header>\n <div class=\"p-400\">Contenuto del dialogo</div>\n</mds-modal>\n```\n\n#### Do Not Size the Window of a Dialog by Hand\n\nA slotted window already stops at the width of a dialog, the column of a form plus its inset (`widths/dialog`), and shrinks with the screen. A width written by hand copies a value the theme no longer moves, and a narrower one breaks the form inside: at `max-w-md` (448px) the body of the window is under the `28rem` of `field-group`, so its short fields stack as on a phone.\n\n```html\n<!-- INCORRECT -->\n<mds-modal aria-label=\"Nuovo referente\">\n <mds-banner slot=\"window\" class=\"max-w-md w-full mx-400\" variant=\"light\" tone=\"box\" dismissible headline=\"Nuovo referente\">\n <fieldset class=\"field-group\">...</fieldset>\n </mds-banner>\n</mds-modal>\n\n<!-- CORRECT -->\n<mds-modal aria-label=\"Nuovo referente\">\n <mds-banner slot=\"window\" variant=\"light\" tone=\"box\" dismissible headline=\"Nuovo referente\">\n <fieldset class=\"field-group\">...</fieldset>\n </mds-banner>\n</mds-modal>\n```\n\n#### Do Not Reach Into Shadow Parts to Style the Window\n\nThe only supported customization surface is the public `--mds-modal-*` CSS custom properties and the documented shadow parts (`dialog`, `window`, `action-close`). Targeting internal shadow selectors couples your code to implementation details that will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-modal >>> .window-content {\n padding: 0;\n}\nmds-modal::part(window) > div {\n border: 2px solid red;\n}\n\n/* CORRECT */\nmds-modal {\n --mds-modal-window-distance: calc(var(--spacing) * 400);\n}\n```\n\n#### Do Not Listen for Native `click` on the Backdrop to Close\n\n`mds-modal` emits `mdsModalClose` when it closes (and `mdsModalHide` when the animation finishes). Listening for a raw `click` on the host or backdrop is fragile - the event target varies by browser and shadow DOM boundary, and your handler ignores `interaction=\"strict\"`.\n\n```javascript\n// INCORRECT\ndocument.getElementById('modal').addEventListener('click', (e) => {\n if (e.target === e.currentTarget) modal.opened = undefined;\n});\n\n// CORRECT\ndocument.getElementById('modal').addEventListener('mdsModalClose', () => {\n modal.opened = undefined;\n});\n```\n\n#### Do Not Use `<dialog>` Directly When `<mds-modal>` Is Available\n\nUsing a raw `<dialog>` element bypasses the system's managed animation, body-scroll locking, touch-swipe dismissal, and design-token theming. Always use `<mds-modal>` for overlays in a Magma application.\n\n```html\n<!-- INCORRECT -->\n<dialog id=\"raw-dialog\">\n <p>Contenuto del dialogo</p>\n <button>Chiudi</button>\n</dialog>\n\n<!-- CORRECT -->\n<mds-modal id=\"modal\">\n <div class=\"p-400\">\n <mds-text>Contenuto del dialogo</mds-text>\n </div>\n</mds-modal>\n```\n"
21645
22158
  },
21646
22159
  "props": [
@@ -21768,7 +22281,7 @@
21768
22281
  "mutable": false,
21769
22282
  "attr": "interaction",
21770
22283
  "reflectToAttr": true,
21771
- "docs": "Specifies if the component can be closed with close button, or also if the backdrop background is cliccked.\nIf `strict` is selected only the close button can dismiss the component via UI.\nIf `relaxed` is selected the component can be dismissed also by cliccking the backdrop area.",
22284
+ "docs": "Specifies if the component can be closed with close button, or also if the backdrop background is cliccked.\nIf `strict` is selected only the close button can dismiss the component via UI.\nIf `relaxed` is selected the component can be dismissed also by clicking the backdrop area: a click\npressed and released on the backdrop, once the window has finished its entry.",
21772
22285
  "docsTags": [
21773
22286
  {
21774
22287
  "name": "default",
@@ -22157,8 +22670,8 @@
22157
22670
  "mds-button"
22158
22671
  ],
22159
22672
  "mds-button": [
22160
- "mds-spinner",
22161
22673
  "mds-icon",
22674
+ "mds-spinner",
22162
22675
  "mds-text"
22163
22676
  ],
22164
22677
  "mds-header": [
@@ -22390,8 +22903,8 @@
22390
22903
  "mds-button"
22391
22904
  ],
22392
22905
  "mds-button": [
22393
- "mds-spinner",
22394
22906
  "mds-icon",
22907
+ "mds-spinner",
22395
22908
  "mds-text"
22396
22909
  ]
22397
22910
  },
@@ -23340,8 +23853,8 @@
23340
23853
  "mds-button"
23341
23854
  ],
23342
23855
  "mds-button": [
23343
- "mds-spinner",
23344
23856
  "mds-icon",
23857
+ "mds-spinner",
23345
23858
  "mds-text"
23346
23859
  ],
23347
23860
  "mds-banner": [
@@ -23389,9 +23902,9 @@
23389
23902
  }
23390
23903
  ],
23391
23904
  "usage": {
23392
- "1. Description": "The `<mds-pref>` web component is the accessibility-preferences panel of the Magma Design System: a compound parent that groups user-facing settings (animation, consumption, contrast, theme, language) so people can tune readability, motion, and language for their session. It acts as the coordinator for the `mds-pref-*` children slotted inside it.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-mode`, `mds-pref-theme` and/or `mds-pref-language` children in its default slot; it owns no preference UI of its own beyond coordination (a scheme-constrained `mds-pref-theme` locks the matching `mds-pref-mode` item).\n- **Size propagation**: `size` cascades down to every nested `mds-pref-*` child, on load, on every change and to the children added later; without a `size` on the panel each child keeps its own.\n- **Reload notice**: The panel shows an inline caption prompting the user to refresh the page when a preference that cannot apply live (`consumption` or `language`) changes after load. A `controller` panel, which is hidden, shows none.\n- **Document flag**: While at least one `<mds-pref>` is on the page, `<html>` carries `data-magma-pref`, which turns off the styles' fallback to the OS preferences; it is removed only when the last instance leaves the page, so a settings page that unmounts its own panel leaves the app controller in charge. Moving a panel in the DOM (between a sidebar and a menu, or with a client router that keeps it across pages) keeps the flag, the reload notice and the theme lock on the mode control.\n- **Live language sync**: When a `language` change is emitted, the panel re-resolves its own locale so the reload notice is shown in the newly selected language.\n\n#### Properties & Visual Configurations\n\n`size` is one of the shared tab sizes and is forwarded to children rather than styling the host directly - set it on the parent and it reaches every child.\n\n#### Other behavioral props\n\n- **`controller`** switches the component from a visible on-DOM panel into a headless controller that applies and reacts to preferences without rendering UI; in this mode it drives document-level preference state without a visible panel.\n",
23393
- "2. Examples": "Correct and idiomatic ways to use the `<mds-pref>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Full Preferences Panel\n\nThe canonical form: slot every `mds-pref-*` control directly inside `<mds-pref>`. The parent coordinates the theme and mode controls automatically (a scheme-constrained theme locks the matching mode item) - no extra wiring is needed.\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-theme>\n <mds-pref-theme-item name=\"default\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"cool\"></mds-pref-theme-item>\n </mds-pref-theme>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Partial Panel - Subset of Controls\n\nSlot only the controls your application needs. `<mds-pref>` renders whatever children are present; omitted controls are simply absent.\n\n```html\n<!-- Accessibility-only panel: contrast and animation controls -->\n<mds-pref>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Controlling Size\n\nThe parent's `size` drives all child controls at once, on load and when it changes.\n\n```html\n<!-- Compact panel for a sidebar or popover -->\n<mds-pref size=\"sm\">\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Headless Controller Mode\n\nSet the `controller` boolean attribute when you need the preference engine to apply saved preferences from `localStorage` on page load without rendering any visible UI. The host is hidden via CSS (`display: none`) and still activates all child preference controls.\n\n```html\n<!-- Place in <body>; the panel is invisible but activates stored preferences -->\n<mds-pref controller>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Language Selector with Multiple Languages\n\n`<mds-pref-language>` requires its child `<mds-pref-language-item>` elements to be present; the items are not self-generating. Pass language codes supported by your application.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Reload Notice Handling\n\n`<mds-pref>` shows an inline caption telling the user to refresh the page after a `consumption` or `language` change: nothing to wire. It shows for a change made after the panel loaded, so the stored choices the controls apply on load raise no notice; a `controller` panel is hidden and shows none.\n",
23394
- "3. Mistakes": "Common incorrect uses of `<mds-pref>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Place Non-Pref Children in the Default Slot\n\nThe default slot accepts only `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-language`, `mds-pref-mode` and `mds-pref-theme` children. Other elements are outside the documented content: they render as extra rows of the panel and take part in no coordination.\n\n```html\n<!-- INCORRECT -->\n<mds-pref>\n <div class=\"custom-section\">Tema</div>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Use `mds-pref-*` Children Outside `<mds-pref>`\n\nEach control applies and stores its own preference, but the coordination between the controls of a panel lives in the parent: a scheme-constrained `mds-pref-theme` item locks the matching `mds-pref-mode` item only inside `<mds-pref>`, and only the parent forwards `size` changes. Group the controls of a panel in `<mds-pref>`.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-mode></mds-pref-mode>\n<mds-pref-theme>\n <mds-pref-theme-item name=\"default\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"cool\"></mds-pref-theme-item>\n</mds-pref-theme>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-theme>\n <mds-pref-theme-item name=\"default\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"cool\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Do Not Set `controller=\"false\"` to Turn Off Controller Mode\n\n`controller` is a boolean attribute, and a false boolean is an absent attribute ([`agents/conventions.md`](../../../../agents/conventions.md)). The runtime parses the string `\"false\"` as `false`, so the panel shows, but the attribute is still on the element until the first render, so `[controller]` attribute selectors (the one that hides the panel included) and any code that reads the attribute see it set. Remove the attribute entirely to switch back to visible mode.\n\n```html\n<!-- INCORRECT -->\n<mds-pref controller=\"false\">\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Listen for the Native `change` Event to Detect Preference Changes\n\nThe controls fire no native `change` event. Use the documented `mdsPrefChange` event emitted by each `mds-pref-*` child: it fires once per change, not on page load, and carries only the `preference` name in `detail`, so read the new value from the child.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelector('mds-pref').addEventListener('change', (e) => {\n console.log(e);\n });\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-pref-mode').addEventListener('mdsPrefChange', (e) => {\n console.log(e.detail.preference);\n });\n</script>\n```\n"
23905
+ "1. Description": "The `<mds-pref>` web component is the accessibility-preferences panel of the Magma Design System: a compound parent that groups user-facing settings (animation, consumption, contrast, theme, language) so people can tune readability, motion, and language for their session. It acts as the coordinator for the `mds-pref-*` children slotted inside it.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-mode`, `mds-pref-theme` and/or `mds-pref-language` children in its default slot; it owns no preference UI of its own beyond coordination (it forwards `size`, flags the document and asks for a reload). The lock of a single-mode theme on `mds-pref-mode` needs no parent: the mode control reads it from `<html>`.\n- **Size propagation**: `size` cascades down to every nested `mds-pref-*` child, on load, on every change and to the children added later; without a `size` on the panel each child keeps its own.\n- **Reload notice**: The panel shows an inline caption prompting the user to refresh the page when a preference that cannot apply live (`consumption` or `language`) changes after load. A `controller` panel, which is hidden, shows none.\n- **Live language**: Magma components follow `<html lang>` at once; the content of the application may not, which is why a change of language asks for a reload. An application that translates its own content as `<html lang>` changes says so with `live-language`, and the panel asks for no reload after a change of language (a change of consumption still asks).\n- **Document flag**: While at least one `<mds-pref>` is on the page, `<html>` carries `data-magma-pref`, which turns off the styles' fallback to the OS preferences; it is removed only when the last instance leaves the page, so a settings page that unmounts its own panel leaves the app controller in charge. Moving a panel in the DOM (between a sidebar and a menu, or with a client router that keeps it across pages) keeps the flag and the reload notice.\n- **Live language sync**: When a `language` change is emitted, the panel re-resolves its own locale so the reload notice is shown in the newly selected language.\n\n#### Properties & Visual Configurations\n\n`size` is one of the shared tab sizes and is forwarded to children rather than styling the host directly - set it on the parent and it reaches every child.\n\n#### Other behavioral props\n\n- **`live-language`** tells the panel the application follows `<html lang>` on its own, so a change of language shows no reload notice.\n- **`controller`** switches the component from a visible on-DOM panel into a headless controller that applies and reacts to preferences without rendering UI; in this mode it drives document-level preference state without a visible panel.\n",
23906
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-pref>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Full Preferences Panel\n\nThe canonical form: slot every `mds-pref-*` control directly inside `<mds-pref>`. No extra wiring is needed: the mode control follows the active theme by itself (a theme of one mode locks it to that mode).\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-theme>\n <mds-pref-theme-item name=\"default\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"cool\"></mds-pref-theme-item>\n </mds-pref-theme>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Partial Panel - Subset of Controls\n\nSlot only the controls your application needs. `<mds-pref>` renders whatever children are present; omitted controls are simply absent.\n\n```html\n<!-- Accessibility-only panel: contrast and animation controls -->\n<mds-pref>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Controlling Size\n\nThe parent's `size` drives all child controls at once, on load and when it changes.\n\n```html\n<!-- Compact panel for a sidebar or popover -->\n<mds-pref size=\"sm\">\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Headless Controller Mode\n\nSet the `controller` boolean attribute when you need the preference engine to apply saved preferences from `localStorage` on page load without rendering any visible UI. The host is hidden via CSS (`display: none`) and still activates all child preference controls.\n\n```html\n<!-- Place in <body>; the panel is invisible but activates stored preferences -->\n<mds-pref controller>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Language Selector with Multiple Languages\n\n`<mds-pref-language>` requires its child `<mds-pref-language-item>` elements to be present; the items are not self-generating. Pass language codes supported by your application.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Reload Notice Handling\n\n`<mds-pref>` shows an inline caption telling the user to refresh the page after a `consumption` or `language` change: nothing to wire. It shows for a change made after the panel loaded, so the stored choices the controls apply on load raise no notice; a `controller` panel is hidden and shows none.\n\n#### An Application That Follows the Language Live\n\nWhen the application translates its own content as `<html lang>` changes (it observes the attribute, or re-renders on `mdsPrefLanguageChange`), add `live-language`: a change of language then needs no reload, and the panel asks for none. A change of consumption still asks.\n\n```html\n<mds-pref live-language>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n",
23907
+ "3. Mistakes": "Common incorrect uses of `<mds-pref>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Place Non-Pref Children in the Default Slot\n\nThe default slot accepts only `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-language`, `mds-pref-mode` and `mds-pref-theme` children. Other elements are outside the documented content: they render as extra rows of the panel and take part in no coordination.\n\n```html\n<!-- INCORRECT -->\n<mds-pref>\n <div class=\"custom-section\">Tema</div>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Use `mds-pref-*` Children Outside `<mds-pref>`\n\nEach control applies and stores its own preference, but the coordination between the controls of a panel lives in the parent: only the parent forwards `size` changes and sets the `data-magma-pref` flag that turns off the fallback to the OS preferences. Group the controls of a panel in `<mds-pref>`.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-mode></mds-pref-mode>\n<mds-pref-theme>\n <mds-pref-theme-item name=\"default\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"cool\"></mds-pref-theme-item>\n</mds-pref-theme>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-theme>\n <mds-pref-theme-item name=\"default\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"cool\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Do Not Set `controller=\"false\"` to Turn Off Controller Mode\n\n`controller` is a boolean attribute, and a false boolean is an absent attribute ([`agents/conventions.md`](../../../../agents/conventions.md)). The runtime parses the string `\"false\"` as `false`, so the panel shows, but the attribute is still on the element until the first render, so `[controller]` attribute selectors (the one that hides the panel included) and any code that reads the attribute see it set. Remove the attribute entirely to switch back to visible mode.\n\n```html\n<!-- INCORRECT -->\n<mds-pref controller=\"false\">\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Listen for the Native `change` Event to Detect Preference Changes\n\nThe controls fire no native `change` event. Use the documented `mdsPrefChange` event emitted by each `mds-pref-*` child: it fires once per change, not on page load, and carries only the `preference` name in `detail`, so read the new value from the child.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelector('mds-pref').addEventListener('change', (e) => {\n console.log(e);\n });\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-pref-mode').addEventListener('mdsPrefChange', (e) => {\n console.log(e.detail.preference);\n });\n</script>\n```\n"
23395
23908
  },
23396
23909
  "props": [
23397
23910
  {
@@ -23420,6 +23933,32 @@
23420
23933
  "getter": false,
23421
23934
  "setter": false
23422
23935
  },
23936
+ {
23937
+ "name": "liveLanguage",
23938
+ "type": "boolean | undefined",
23939
+ "complexType": {
23940
+ "original": "boolean",
23941
+ "resolved": "boolean | undefined",
23942
+ "references": {}
23943
+ },
23944
+ "mutable": false,
23945
+ "attr": "live-language",
23946
+ "reflectToAttr": true,
23947
+ "docs": "Tells the panel that the application follows `<html lang>` on its own, translating its\ncontent as the language changes, so a change of language needs no reload and shows no notice",
23948
+ "docsTags": [],
23949
+ "values": [
23950
+ {
23951
+ "type": "boolean"
23952
+ },
23953
+ {
23954
+ "type": "undefined"
23955
+ }
23956
+ ],
23957
+ "optional": true,
23958
+ "required": false,
23959
+ "getter": false,
23960
+ "setter": false
23961
+ },
23423
23962
  {
23424
23963
  "name": "size",
23425
23964
  "type": "\"md\" | \"sm\" | undefined",
@@ -23466,11 +24005,6 @@
23466
24005
  "event": "mdsPrefChange",
23467
24006
  "capture": false,
23468
24007
  "passive": false
23469
- },
23470
- {
23471
- "event": "mdsPrefThemeChange",
23472
- "capture": false,
23473
- "passive": false
23474
24008
  }
23475
24009
  ],
23476
24010
  "styles": [],
@@ -23637,8 +24171,8 @@
23637
24171
  "mds-button"
23638
24172
  ],
23639
24173
  "mds-button": [
23640
- "mds-spinner",
23641
24174
  "mds-icon",
24175
+ "mds-spinner",
23642
24176
  "mds-text"
23643
24177
  ]
23644
24178
  },
@@ -23788,8 +24322,8 @@
23788
24322
  "mds-button"
23789
24323
  ],
23790
24324
  "mds-button": [
23791
- "mds-spinner",
23792
24325
  "mds-icon",
24326
+ "mds-spinner",
23793
24327
  "mds-text"
23794
24328
  ]
23795
24329
  },
@@ -23939,8 +24473,8 @@
23939
24473
  "mds-button"
23940
24474
  ],
23941
24475
  "mds-button": [
23942
- "mds-spinner",
23943
24476
  "mds-icon",
24477
+ "mds-spinner",
23944
24478
  "mds-text"
23945
24479
  ]
23946
24480
  },
@@ -23963,7 +24497,7 @@
23963
24497
  }
23964
24498
  ],
23965
24499
  "usage": {
23966
- "1. Description": "The `<mds-pref-language>` web component is the language-preference control of the Magma Design System, usually slotted inside the [`<mds-pref>`](../mds-pref/AGENTS.md) panel alongside the other preference children. It renders a labelled tab trigger that opens a dropdown of `<mds-pref-language-item>` entries, letting users switch the active document language and persisting that choice.\n\n#### Semantic Behavior\n\n- **Usually inside `<mds-pref>`**: Placed as a direct slot child of `<mds-pref>`, alongside the other `mds-pref-*` controls; it also works on its own, since it applies and stores the language by itself. What it gives up on its own is in its mistakes. In turn it hosts its own `<mds-pref-language-item>` children, supplied via its default slot.\n- **Default slot hosts the items**: The default slot accepts one or more `<mds-pref-language-item>` elements; when the control loads, and whenever its items change, the item whose `code` matches the resolved language is marked selected; an item added after load is picked like the others (a later change of `set` does not move the selection).\n- **Selection orchestration**: Selecting an item clears the others, closes the dropdown, and resolves the new language - the children report up to this component, which centralizes the single-selection state.\n- **Language resolution & persistence**: When `set` is `auto` the active language is resolved in priority order from the persisted value, then the `<html lang>` attribute, then `navigator.language`. The resolved value is persisted and written to `<html lang>` - the single page-wide source of truth for the language. Every localized Magma component (including ones nested in shadow DOM) reacts automatically through a shared reactive store; there is no per-element `lang` override and no imperative refresh method. Applications that manage the language themselves can simply set `<html lang>`: the store observes it.\n- **Events bubbled to the parent**: Emits `mdsPrefLanguageChange` on every item pick, also when the picked language is already active (detail carries the selected `language` code; it fires just before the language is applied), and `mdsPrefChange` (detail `{ preference: 'language' }`), fired only when the resolved language actually changes, from a pick or from a new `set` value (the initial application on load does not emit). The latter is the event `<mds-pref>` listens to for its \"reload required\" notice, since application-level content may still need a reload.\n- **Invalid codes are ignored**: A `set` value that is neither `auto` nor a language tag (a primary subtag of two or three letters, such as `it` or `haw`, optionally followed by others, such as `it-IT`) is ignored with a console warning: the language in place stays, and on load the one `auto` resolves. A stored value that is no language tag is dropped.\n- **Default-language hint**: When the resolved language differs from the built-in default (`en`), a caption noting the default language is rendered.\n\n#### Properties & Visual Configurations\n\n- **`set`**: The desired language as a BCP 47 short tag (e.g. `it`, `en`, `es-ES`); the special value `auto` (default) defers to the persisted/page/system resolution chain described above. Region subtags are sanitized down to the two-letter language. Set an explicit value only to force a starting language regardless of the user's environment. Supported display languages are Italiano, English, Español and ελληνικά.\n- **`size`**: Sizes the nested tab trigger (`sm` / `md`). Inside `<mds-pref>`, the parent's `size` reaches this control on load and when it changes, and overwrites its own: set it on the parent.\n",
24500
+ "1. Description": "The `<mds-pref-language>` web component is the language-preference control of the Magma Design System, usually slotted inside the [`<mds-pref>`](../mds-pref/AGENTS.md) panel alongside the other preference children. It renders a labelled tab trigger that opens a dropdown of `<mds-pref-language-item>` entries, letting users switch the active document language and persisting that choice.\n\n#### Semantic Behavior\n\n- **Usually inside `<mds-pref>`**: Placed as a direct slot child of `<mds-pref>`, alongside the other `mds-pref-*` controls; it also works on its own, since it applies and stores the language by itself. What it gives up on its own is in its mistakes. In turn it hosts its own `<mds-pref-language-item>` children, supplied via its default slot.\n- **Default slot hosts the items**: The default slot accepts one or more `<mds-pref-language-item>` elements; when the control loads, and whenever its items change, the item whose `code` matches the resolved language is marked selected; an item added after load is picked like the others (a later change of `set` does not move the selection).\n- **Selection orchestration**: Selecting an item clears the others, closes the dropdown, and resolves the new language - the children report up to this component, which centralizes the single-selection state.\n- **Language resolution & persistence**: When `set` is `auto` the active language is resolved in priority order from the persisted value, then the `<html lang>` attribute, then `navigator.language`. The resolved value is persisted and written to `<html lang>` - the single page-wide source of truth for the language. Every localized Magma component (including ones nested in shadow DOM) reacts automatically through a shared reactive store; there is no per-element `lang` override and no imperative refresh method. Applications that manage the language themselves can simply set `<html lang>`: the store observes it.\n- **Events bubbled to the parent**: Emits `mdsPrefLanguageChange` on every item pick, also when the picked language is already active (detail carries the selected `language` code; it fires just before the language is applied), and `mdsPrefChange` (detail `{ preference: 'language' }`), fired only when the resolved language actually changes, from a pick or from a new `set` value (the initial application on load does not emit). The latter is the event `<mds-pref>` listens to for its \"reload required\" notice, since application-level content may still need a reload; an application that follows `<html lang>` live sets `live-language` on the panel, which then shows no notice for the language.\n- **Invalid codes are ignored**: A `set` value that is neither `auto` nor a language tag (a primary subtag of two or three letters, such as `it` or `haw`, optionally followed by others, such as `it-IT`) is ignored with a console warning: the language in place stays, and on load the one `auto` resolves. A stored value that is no language tag is dropped.\n- **Default-language hint**: When the resolved language differs from the built-in default (`en`), a caption noting the default language is rendered.\n\n#### Properties & Visual Configurations\n\n- **`set`**: The desired language as a BCP 47 short tag (e.g. `it`, `en`, `es-ES`); the special value `auto` (default) defers to the persisted/page/system resolution chain described above. Region subtags are sanitized down to the two-letter language. Set an explicit value only to force a starting language regardless of the user's environment. Supported display languages are Italiano, English, Español and ελληνικά.\n- **`size`**: Sizes the nested tab trigger (`sm` / `md`). Inside `<mds-pref>`, the parent's `size` reaches this control on load and when it changes, and overwrites its own: set it on the parent.\n",
23967
24501
  "2. Examples": "Correct and idiomatic ways to use the `<mds-pref-language>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Language Selector Inside `mds-pref`\n\nThe canonical usage. Nest `<mds-pref-language>` as a direct child of [`<mds-pref>`](../mds-pref/AGENTS.md) and populate its default slot with one [`<mds-pref-language-item>`](../mds-pref-language-item/AGENTS.md) per supported locale. The `code` attribute on each item must be a valid BCP 47 short tag.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Forcing a Starting Language with `set`\n\nPass an explicit BCP 47 tag to `set` to override the automatic resolution chain. Use this when the application dictates an initial language regardless of the user's browser setting or persisted preference.\n\n```html\n<mds-pref>\n <mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Automatic Language Resolution (default)\n\nOmit `set` (or pass `set=\"auto\"`) to let the component resolve the active language in priority order: persisted user choice, then the page `<html lang>` attribute, then `navigator.language`. This is the right choice for most applications.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Sizing via `size`\n\nUse the `size` prop to size the tab trigger of a standalone control. Inside [`<mds-pref>`](../mds-pref/AGENTS.md), set `size` on the parent: it forwards it to every `mds-pref-*` child, so the group stays consistent.\n\n```html\n<mds-pref size=\"sm\">\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Listening for Language Changes\n\nListen to `mdsPrefLanguageChange` to react when the user picks a language (for example, to reload the page or re-fetch translated content). The event detail carries the selected `language` code string. It fires on every pick, also when the picked language is already the active one.\n\n```html\n<mds-pref>\n <mds-pref-language id=\"lang-selector\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n\n<script>\n document.querySelector('#lang-selector').addEventListener('mdsPrefLanguageChange', (e) => {\n console.log('Nuova lingua selezionata:', e.detail.language);\n // e.g. reload the page to apply the new locale\n window.location.reload();\n });\n</script>\n```\n\n#### Full Preference Panel with Language\n\n`<mds-pref-language>` is one of several preference children accepted by [`<mds-pref>`](../mds-pref/AGENTS.md). Compose it alongside the other controls to offer a complete preferences UI.\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n",
23968
24502
  "3. Mistakes": "Common incorrect uses of `<mds-pref-language>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use Outside `mds-pref`\n\n`<mds-pref-language>` is a compound child designed to live inside [`<mds-pref>`](../mds-pref/AGENTS.md). As a standalone widget it still applies and persists the language, but it leaves the preference group: `<mds-pref>` forwards `size` changes to its `mds-pref-*` children and listens to their `mdsPrefChange` for the reload-required notice.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n</mds-pref-language>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Do Not Slot Arbitrary HTML Instead of `mds-pref-language-item`\n\nThe default slot accepts only `<mds-pref-language-item>` elements. Slotting raw `<button>`, `<li>`, or other elements bypasses the selection orchestration and event wiring the parent depends on.\n\n```html\n<!-- INCORRECT -->\n<mds-pref>\n <mds-pref-language>\n <button>Italiano</button>\n <button>English</button>\n </mds-pref-language>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Do Not Pass an Unrecognized Language Code to `set`\n\nThe `set` prop must be either `\"auto\"` or a BCP 47 language tag: a primary subtag of two or three letters, the one of the item dictionary (`it`, `en`, `haw`), optionally followed by others (`it-IT`). Any other value - including language names like `\"italiano\"` or malformed strings like `\"en_US\"` - is ignored with a console warning and the language in place stays. Use the shortest primary subtag: `it`, not the ISO 639-2 `ita`, which has no item and no translation.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-language set=\"italiano\">...</mds-pref-language>\n<mds-pref-language set=\"en_US\">...</mds-pref-language>\n\n<!-- CORRECT -->\n<mds-pref-language set=\"it\">...</mds-pref-language>\n<mds-pref-language set=\"en\">...</mds-pref-language>\n<mds-pref-language set=\"es-ES\">...</mds-pref-language>\n```\n\n#### Do Not Set `selected` Manually on `mds-pref-language-item`\n\nThe parent `<mds-pref-language>` manages the `selected` state of each item automatically based on the active language: when it loads, and whenever its items change, it marks only the item whose `code` matches, and on each pick it clears the siblings. A `selected` written in the markup is overwritten on load; one set later from script leaves the visual selection out of step with the active language.\n\n```html\n<!-- INCORRECT -->\n<mds-pref>\n <mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\" selected></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n\n<!-- CORRECT - the parent derives selection from `set` -->\n<mds-pref>\n <mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Do Not Listen to `mdsPrefLanguageItemSelect` Instead of `mdsPrefLanguageChange`\n\n`mdsPrefLanguageItemSelect` is the item's own event, emitted by `<mds-pref-language-item>` and consumed by its parent. Application code should listen to `mdsPrefLanguageChange` on `<mds-pref-language>`: one listener for the whole list, fired after the parent has committed the selection (the language is applied right after it, so read it from `e.detail.language`).\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelector('mds-pref-language-item').addEventListener('mdsPrefLanguageItemSelect', (e) => {\n console.log(e.detail.language);\n });\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-pref-language').addEventListener('mdsPrefLanguageChange', (e) => {\n console.log(e.detail.language);\n });\n</script>\n```\n\n#### Do Not Set Size via CSS Instead of the `size` Prop\n\nThe `size` prop is the only supported way to resize the internal tab trigger. Overriding dimensions with inline styles or CSS custom properties not listed in the component's documented surface couples your code to internal implementation details.\n\n```css\n/* INCORRECT */\nmds-pref-language mds-tab-item {\n font-size: 10px;\n}\n```\n\n```html\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-language size=\"sm\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n"
23969
24503
  },
@@ -24119,8 +24653,8 @@
24119
24653
  "mds-button"
24120
24654
  ],
24121
24655
  "mds-button": [
24122
- "mds-spinner",
24123
24656
  "mds-icon",
24657
+ "mds-spinner",
24124
24658
  "mds-text"
24125
24659
  ]
24126
24660
  },
@@ -24243,8 +24777,8 @@
24243
24777
  "mds-button"
24244
24778
  ],
24245
24779
  "mds-button": [
24246
- "mds-spinner",
24247
24780
  "mds-icon",
24781
+ "mds-spinner",
24248
24782
  "mds-text"
24249
24783
  ]
24250
24784
  },
@@ -24263,9 +24797,9 @@
24263
24797
  }
24264
24798
  ],
24265
24799
  "usage": {
24266
- "1. Description": "The `<mds-pref-mode>` web component is the mode preference control of the Magma Design System, usually a direct child of the [`<mds-pref>`](../mds-pref/AGENTS.md) panel. It renders a labelled three-way tab (light / system / dark) that lets the user pick a color-scheme mode and applies it globally to the document.\n\n#### Semantic Behavior\n\n- **Usually inside `<mds-pref>`**: Placed as a direct slot child of `<mds-pref>`, alongside the other `mds-pref-*` controls; it also works on its own, since it applies and stores the mode by itself. What it gives up on its own is in its mistakes.\n- **Selection follows `mode`**: The active tab reflects whichever mode is currently applied, driven by the `mode` prop.\n- **Global mode application**: Selecting a mode applies it document-wide and persists the choice.\n- **Persistence on load**: The applied mode resolves from `mode` -> the stored value -> the `system` default, so a previously chosen mode is restored without an explicit prop.\n- **`mdsPrefChange` event**: Emits `mdsPrefChange` with `{ preference: 'mode' }` once per change, after the new mode is applied; a pick of the mode already active and the first application on load do not emit it. It bubbles up to `<mds-pref>`; a mode change needs no reload, so it raises no reload notice.\n- **Instances stay in sync**: Instances mounted together (a hidden `<mds-pref controller>` and a visible settings panel) share the applied mode: a pick in one is mirrored by the others, which neither apply it again nor emit `mdsPrefChange`. A `pref-mode-*` class written on `<html>` by other code is mirrored the same way.\n- **System mode**: The `system` choice follows the OS `prefers-color-scheme` media query to resolve the effective light/dark scheme.\n\n#### Properties & Visual Configurations\n\n- **`mode`**: Sets and reflects the active mode (`light`, `dark`, `system`). Leave it unset to inherit the persisted/default mode; set it explicitly to force a starting mode.\n- **`transition`**: Controls the visual switch between schemes. Use `smooth` (default) for a fading neutral overlay that flips the mode mid-fade, `flash` for an instant switch with a brief overlay pulse, or `none` to apply the new mode with no overlay animation. The overlay timing and z-index are tunable through `--mds-pref-mode-overlay-*` CSS custom properties.\n- **`size`**: Sizes the nested tab items (`sm` / `md`). Inside `<mds-pref>`, set it on the parent instead: the parent's `size` reaches every `mds-pref-*` child on load and when it changes, and overwrites the child's own.\n",
24800
+ "1. Description": "The `<mds-pref-mode>` web component is the mode preference control of the Magma Design System, usually a direct child of the [`<mds-pref>`](../mds-pref/AGENTS.md) panel. It renders a labelled three-way tab (light / system / dark) that lets the user pick a color-scheme mode and applies it globally to the document.\n\n#### Semantic Behavior\n\n- **Usually inside `<mds-pref>`**: Placed as a direct slot child of `<mds-pref>`, alongside the other `mds-pref-*` controls; it also works on its own, since it applies and stores the mode by itself. What it gives up on its own is in its mistakes.\n- **Selection follows `mode`**: The active tab reflects whichever mode is currently applied, driven by the `mode` prop.\n- **Global mode application**: Selecting a mode applies it document-wide and persists the choice.\n- **Persistence on load**: The applied mode resolves from `mode` -> the stored value -> the `system` default, so a previously chosen mode is restored without an explicit prop.\n- **`mdsPrefChange` event**: Emits `mdsPrefChange` with `{ preference: 'mode' }` once per change, after the new mode is applied; a pick of the mode already active and the first application on load do not emit it. It bubbles up to `<mds-pref>`; a mode change needs no reload, so it raises no reload notice.\n- **Instances stay in sync**: Instances mounted together (a hidden `<mds-pref controller>` and a visible settings panel) share the applied mode: a pick in one is mirrored by the others, which neither apply it again nor emit `mdsPrefChange`. A `pref-mode-*` class written on `<html>` by other code is mirrored the same way.\n- **System mode**: The `system` choice follows the OS `prefers-color-scheme` media query to resolve the effective light/dark scheme.\n- **Theme lock**: Under a theme that can be used in one mode only (`pref-theme-scheme-light` or `-dark` on `<html>`, written by `mds-pref-theme` from the mode the theme declares), the control shows that mode selected and disables the other two items: the page is in that mode whatever was picked. The stored choice is left alone and comes back with a theme of both modes.\n\n#### Properties & Visual Configurations\n\n- **`mode`**: Sets and reflects the active mode (`light`, `dark`, `system`). Leave it unset to inherit the persisted/default mode; set it explicitly to force a starting mode.\n- **`transition`**: Controls the visual switch between schemes. Use `smooth` (default) for a fading neutral overlay that flips the mode mid-fade, `flash` for an instant switch with a brief overlay pulse, or `none` to apply the new mode with no overlay animation. The overlay timing and z-index are tunable through `--mds-pref-mode-overlay-*` CSS custom properties.\n- **`size`**: Sizes the nested tab items (`sm` / `md`). Inside `<mds-pref>`, set it on the parent instead: the parent's `size` reaches every `mds-pref-*` child on load and when it changes, and overwrites the child's own.\n",
24267
24801
  "2. Examples": "Correct and idiomatic ways to use the `<mds-pref-mode>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared preference system documented in [`agents/theming.md`](../../../../agents/theming.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Default Usage Inside `mds-pref`\n\nThe canonical form. Slot `<mds-pref-mode>` as a direct child of [`<mds-pref>`](../mds-pref/AGENTS.md) with no extra props. The component restores the user's previously persisted mode automatically on load.\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Setting an Initial Mode\n\nPass `mode` to force the selector to start on a specific mode rather than reading from `localStorage`. Useful when the host application controls preference state centrally. The forced mode is also written to `localStorage` on every load, replacing the user's last choice.\n\n```html\n<mds-pref>\n <mds-pref-mode mode=\"dark\"></mds-pref-mode>\n</mds-pref>\n```\n\n#### Using `system` Mode for OS-Aware Default\n\n`mode=\"system\"` resolves to light or dark based on the OS `prefers-color-scheme` media query. Use this as the explicit starting point when you want the app to follow the OS without the user having to choose.\n\n```html\n<mds-pref>\n <mds-pref-mode mode=\"system\"></mds-pref-mode>\n</mds-pref>\n```\n\n#### Choosing a Transition Style\n\n`transition` controls the visual effect when switching between schemes. Use `smooth` (default) for a mid-fade overlay that hides the color flip, `flash` for an instant switch with a brief full-screen pulse, or `none` for a hard switch with no animation.\n\n```html\n<!-- Smooth fade (default) -->\n<mds-pref-mode transition=\"smooth\"></mds-pref-mode>\n\n<!-- Instant flash pulse -->\n<mds-pref-mode transition=\"flash\"></mds-pref-mode>\n\n<!-- No animation -->\n<mds-pref-mode transition=\"none\"></mds-pref-mode>\n```\n\n#### Listening for Mode Changes\n\nThe component emits `mdsPrefChange` with `{ preference: 'mode' }` once per change, after the new mode is applied, and not on page load; another instance that mirrors the pick does not emit it. Listen for this event to react in application code - for example to sync a preference state store - and read the current value from the `mode` prop.\n\n```html\n<mds-pref>\n <mds-pref-mode id=\"mode-selector\"></mds-pref-mode>\n</mds-pref>\n\n<script>\n document.getElementById('mode-selector').addEventListener('mdsPrefChange', (e) => {\n console.log('Modalita tema cambiata:', e.detail.preference);\n });\n</script>\n```\n\n#### Controlling Size via the Parent\n\n`size` is forwarded to the internal tab items. [`<mds-pref>`](../mds-pref/AGENTS.md) forwards its own `size` to every `mds-pref-*` child, on load and when it changes: set it on the parent to keep the panel at one tab size.\n\n```html\n<mds-pref size=\"sm\">\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n</mds-pref>\n```\n\n#### Customizing the Transition Overlay\n\nTune the overlay stacking order via the public `--mds-pref-mode-overlay-z-index` CSS custom property, when the page has layers above the default one; the overlay timing is set by the component. Set it on the host or a parent selector.\n\n```css\nmds-pref-mode {\n --mds-pref-mode-overlay-z-index: 9000;\n}\n```\n",
24268
- "3. Mistakes": "Common incorrect uses of `<mds-pref-mode>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-pref-mode>` Outside `<mds-pref>`\n\n`<mds-pref-mode>` is a compound child: `<mds-pref>` forwards `size` changes to it and locks the mode item that a scheme-constrained `<mds-pref-theme>` forbids (it sets `lockedScheme`). As a standalone widget it still applies and persists the mode, but nothing coordinates it with the theme.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-mode></mds-pref-mode>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Set `transition=\"false\"` to Disable the Overlay\n\n`transition` is a string enum, not a boolean. `\"false\"` is not a valid value: it only happens to fall through to the no-overlay branch, with no guarantee across releases. Use `transition=\"none\"` to opt out of the overlay animation.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-mode transition=\"false\"></mds-pref-mode>\n\n<!-- CORRECT -->\n<mds-pref-mode transition=\"none\"></mds-pref-mode>\n```\n\n#### Do Not Listen for Native `change` Events Instead of `mdsPrefChange`\n\nThe component does not emit or bubble native `change` events out of the shadow DOM. Always listen for the documented `mdsPrefChange` custom event.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelector('mds-pref-mode').addEventListener('change', handler);\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-pref-mode').addEventListener('mdsPrefChange', handler);\n</script>\n```\n\n#### Do Not Override Mode Classes on `<html>` Directly\n\nThe component manages `pref-mode-light`, `pref-mode-dark`, and `pref-mode-system` classes on `<html>` itself. Adding or removing these by hand races with the component and will be overwritten on the next mode change. Drive the mode exclusively through the `mode` prop.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.documentElement.classList.add('pref-mode-dark');\n</script>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode mode=\"dark\"></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Size Only One Child of the Panel\n\nSetting `size` on `<mds-pref-mode>` alone when siblings exist produces inconsistent tab sizes across the panel. Set it on `<mds-pref>`, which forwards it to every preference child, on load and when it changes.\n\n```html\n<!-- INCORRECT -->\n<mds-pref>\n <mds-pref-mode size=\"sm\"></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref size=\"sm\">\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n</mds-pref>\n```\n\n#### Do Not Target the Injected Overlay to Customize It\n\nThe overlay element is injected into `document.body` at runtime with inline styles, which win over a class selector anyway. Do not target it by class name or adjust its properties through JavaScript. Use the public `--mds-pref-mode-overlay-z-index` CSS custom property instead.\n\n```css\n/* INCORRECT */\n.mds-pref-mode-overlay {\n background-color: black;\n z-index: 99999;\n}\n\n/* CORRECT */\nmds-pref-mode {\n --mds-pref-mode-overlay-z-index: 9000;\n}\n```\n"
24802
+ "3. Mistakes": "Common incorrect uses of `<mds-pref-mode>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-pref-mode>` Outside `<mds-pref>`\n\n`<mds-pref-mode>` is a compound child: `<mds-pref>` forwards `size` changes to it. As a standalone widget it still applies and persists the mode, and it still follows a theme of one mode, which it reads from `<html>`; only the forwarding of `size` is lost.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-mode></mds-pref-mode>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Set `transition=\"false\"` to Disable the Overlay\n\n`transition` is a string enum, not a boolean. `\"false\"` is not a valid value: it only happens to fall through to the no-overlay branch, with no guarantee across releases. Use `transition=\"none\"` to opt out of the overlay animation.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-mode transition=\"false\"></mds-pref-mode>\n\n<!-- CORRECT -->\n<mds-pref-mode transition=\"none\"></mds-pref-mode>\n```\n\n#### Do Not Listen for Native `change` Events Instead of `mdsPrefChange`\n\nThe component does not emit or bubble native `change` events out of the shadow DOM. Always listen for the documented `mdsPrefChange` custom event.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelector('mds-pref-mode').addEventListener('change', handler);\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-pref-mode').addEventListener('mdsPrefChange', handler);\n</script>\n```\n\n#### Do Not Override Mode Classes on `<html>` Directly\n\nThe component manages `pref-mode-light`, `pref-mode-dark`, and `pref-mode-system` classes on `<html>` itself. Adding or removing these by hand races with the component and will be overwritten on the next mode change. Drive the mode exclusively through the `mode` prop.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.documentElement.classList.add('pref-mode-dark');\n</script>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode mode=\"dark\"></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Size Only One Child of the Panel\n\nSetting `size` on `<mds-pref-mode>` alone when siblings exist produces inconsistent tab sizes across the panel. Set it on `<mds-pref>`, which forwards it to every preference child, on load and when it changes.\n\n```html\n<!-- INCORRECT -->\n<mds-pref>\n <mds-pref-mode size=\"sm\"></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref size=\"sm\">\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n</mds-pref>\n```\n\n#### Do Not Target the Injected Overlay to Customize It\n\nThe overlay element is injected into `document.body` at runtime with inline styles, which win over a class selector anyway. Do not target it by class name or adjust its properties through JavaScript. Use the public `--mds-pref-mode-overlay-z-index` CSS custom property instead.\n\n```css\n/* INCORRECT */\n.mds-pref-mode-overlay {\n background-color: black;\n z-index: 99999;\n}\n\n/* CORRECT */\nmds-pref-mode {\n --mds-pref-mode-overlay-z-index: 9000;\n}\n```\n"
24269
24803
  },
24270
24804
  "props": [
24271
24805
  {
@@ -24286,7 +24820,7 @@
24286
24820
  "mutable": false,
24287
24821
  "attr": "locked-scheme",
24288
24822
  "reflectToAttr": true,
24289
- "docs": "Locks the mode items forbidden by a scheme-constrained theme, without\ntouching the stored preference: `light` disables the explicit `dark` item,\n`dark` disables the explicit `light` item, `all` (or unset) locks nothing;\nthe `system` item is never locked. Set by the `mds-pref` controller from the\nactive theme's `scheme`; not meant to be set directly.",
24823
+ "docs": "Locks the mode choice to one mode, `light` or `dark`: the control shows that mode\nselected and disables the other two items, without touching the stored preference,\nwhich comes back when the lock goes. `all` locks nothing. Unset, the control follows\nthe active theme: a theme that can be used in one mode only (`pref-theme-scheme-light`\nor `-dark` on `<html>`, written by `mds-pref-theme` from the mode the theme declares,\n#1274) locks it the same way. Not meant to be set directly.",
24290
24824
  "docsTags": [],
24291
24825
  "values": [
24292
24826
  {
@@ -24500,8 +25034,8 @@
24500
25034
  "mds-button"
24501
25035
  ],
24502
25036
  "mds-button": [
24503
- "mds-spinner",
24504
25037
  "mds-icon",
25038
+ "mds-spinner",
24505
25039
  "mds-text"
24506
25040
  ]
24507
25041
  },
@@ -24524,9 +25058,9 @@
24524
25058
  }
24525
25059
  ],
24526
25060
  "usage": {
24527
- "1. Description": "The `<mds-pref-theme>` web component is the theme-switcher segment of the Magma accessibility preferences panel, usually a direct child of [`<mds-pref>`](../mds-pref/AGENTS.md). It renders a labelled tab trigger that opens a dropdown of selectable named themes and, when a theme is chosen, applies it globally to the document.\n\n#### Semantic Behavior\n\n- **Usually inside `<mds-pref>`**: Placed as a direct slot child of `<mds-pref>`, alongside the other `mds-pref-*` controls; it also works on its own, since it applies and stores the theme by itself. What it gives up on its own is in its mistakes.\n- **Acts as a sub-parent itself**: Its own default slot must contain one or more `mds-pref-theme-item` elements; it drives their selected state so only the active theme is marked selected.\n- **Global theme application**: Selecting an item applies the theme document-wide: it writes `data-theme-name` and the `pref-theme-scheme-*` class on `<html>`.\n- **Persistence and hydration**: The current name, scheme and corner shape are persisted and restored across reloads: a stored value outranks the matching prop.\n- **Validation**: An invalid theme name (not lowercase kebab-case matching `^[a-z]+(-[a-z]+)*$`) is ignored with a console warning when the theme is applied: nothing is written on `<html>` or stored. So are the reserved names `light`, `dark` and `system` (they are mode values) and `scheme` or `scheme-*` (they would collide with the `pref-theme-scheme-*` classes), a `scheme` other than `light`, `dark` or `all`, and a `corner-shape` outside its keywords. A stored value the component cannot apply is dropped, and the prop is used instead.\n- **Events bubbled up**: Emits `mdsPrefThemeChange` with the `{ name, scheme }` detail on each pick, which `<mds-pref>` listens to in order to lock the `<mds-pref-mode>` item a scheme-constrained theme forbids. It also emits `mdsPrefChange` once per change, after applying it: `preference: 'theme'` for a new name or scheme, `'corner-shape'` for a new corner shape. The first application on load and a re-render that changes nothing do not emit it.\n- **Props set after load**: A `name`, `scheme` or `cornerShape` set from a script after load is stored and applied, as a pick is: the stored value outranks the prop only on load. A value the component would not apply is not stored.\n- **Localized label**: The \"Theme\" heading follows the active interface language.\n- **Trigger text**: The closed control shows the `label` of the item for the active theme, the same text the open list shows (localize the items, the trigger follows); when no item matches the active theme it shows the label derived from the name (`dark-blue` -> \"Dark blue\").\n\n#### Properties & Visual Configurations\n\n- **`name`**: The active theme name; it is overridden at runtime by any persisted value. Use it to declare the initial theme when no preference has been stored yet. The named themes are `business`, the base theme, and `editorial` ([`agents/theming.md`](../../../../agents/theming.md)). The default `'default'` is the old name of `business`, kept until the next major, when the default becomes `'business'`: the two names stand for the same theme, so with `name` left out the item `business` is the one marked, and an item named `default` is marked under `business`. `cool` and `warm` are deprecated.\n- **`scheme`**: Constrains the colour modes of the theme to `'light'`, `'dark'`, or `'all'` (default). Pick `'all'` for themes that ship both light and dark palettes; pick `'light'` or `'dark'` to force a single mode for a theme offered in one mode only.\n- **`size`**: Sets the size (`'sm'` / `'md'`) of the nested tab UI. Inside `<mds-pref>`, set it on the parent: it reaches every `mds-pref-*` segment on load and when it changes, and overwrites the segment's own.\n- **`cornerShape`** (attribute `corner-shape`): The corner geometry of the whole page - `round`, `squircle`, `bevel`, `notch`, `scoop`, `square`, or `default`. It writes `data-corner-shape` on `<html>` and is persisted like the theme; `default` removes the attribute, and leaving the prop unset touches nothing ([`agents/theming.md`](../../../../agents/theming.md)).\n",
24528
- "2. Examples": "Correct and idiomatic ways to use the `<mds-pref-theme>` component, ordered from most common to most specialized. The examples assume a working knowledge of the preferences system documented in [`agents/theming.md`](../../../../agents/theming.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Theme Chooser\n\nThe canonical form. Place `<mds-pref-theme>` inside [`<mds-pref>`](../mds-pref/AGENTS.md) and populate its default slot with one [`<mds-pref-theme-item>`](../mds-pref-theme-item/AGENTS.md) per available theme. The item whose `name` matches the active theme (the stored choice, or the parent's `name` on a first visit) starts as selected. The named themes are `business`, the base theme of the management software, and `editorial`, the theme of the publishing side.\n\n```html\n<mds-pref>\n <mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Editoriale\" name=\"editorial\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Scheme-Constrained Themes\n\nUse `scheme=\"light\"` or `scheme=\"dark\"` on a `<mds-pref-theme-item>` when the theme must be offered in one colour mode only. The parent component propagates the chosen scheme to `<html>` and forces that mode even if the user's OS or mode preference asks for the opposite; inside `<mds-pref>` the forbidden item of `<mds-pref-mode>` is locked.\n\n```html\n<mds-pref>\n <mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n <!-- light only - dark mode will not activate with this item -->\n <mds-pref-theme-item label=\"Editoriale chiaro\" name=\"editorial\" scheme=\"light\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Listening for the Change Event\n\nReact to the user's selection via `mdsPrefThemeChange`. The event detail carries `{ name, scheme }` - use them to update any app-level state that tracks the active theme.\n\n```html\n<mds-pref>\n <mds-pref-theme id=\"theme-chooser\" name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Editoriale\" name=\"editorial\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n\n<script>\n document.querySelector('#theme-chooser').addEventListener('mdsPrefThemeChange', (e) => {\n console.log('Tema attivo:', e.detail.name, '- Schema:', e.detail.scheme);\n });\n</script>\n```\n\n#### Declaring the Initial Theme\n\nUse the `name` prop to declare which theme should be active before the user makes a selection. If `localStorage` already holds a persisted value it takes precedence; otherwise the component applies `name` on first render.\n\n```html\n<mds-pref>\n <!-- First-visit default is \"editorial\" -->\n <mds-pref-theme name=\"editorial\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Editoriale\" name=\"editorial\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Controlling Item Size\n\nPass `size=\"sm\"` when the preferences panel must fit a compact layout: on `<mds-pref>`, which forwards it to every preference control.\n\n```html\n<mds-pref size=\"sm\">\n <mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Editoriale\" name=\"editorial\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Styling Theme Items\n\nStyle theme items only through their public `--mds-pref-theme-item-*` CSS custom properties. Set them on the item host or on a parent selector; name a semantic role, `rgb(var(--magma-<role>))` ([`agents/color.md`](../../../../agents/color.md)), so the colours follow the mode, the theme and the contrast preference.\n\n```css\nmds-pref-theme-item {\n --mds-pref-theme-item-color-background: rgb(var(--magma-surface-inverse));\n}\n```\n",
24529
- "3. Mistakes": "Common incorrect uses of `<mds-pref-theme>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind colour utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use the Component Outside `<mds-pref>`\n\n`<mds-pref-theme>` is a compound sub-part designed to slot inside [`<mds-pref>`](../mds-pref/AGENTS.md). As a standalone widget it still applies and persists the theme, but it leaves the panel: `<mds-pref>` can no longer forward `size` changes to it, nor lock the `<mds-pref-mode>` item that its `scheme` forbids.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n</mds-pref-theme>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Do Not Put Plain Text or Arbitrary HTML in the Default Slot\n\nThe default slot is reserved exclusively for `<mds-pref-theme-item>` elements. Any other content bypasses the component's internal selection management and will not trigger theme application.\n\n```html\n<!-- INCORRECT -->\n<mds-pref>\n <mds-pref-theme name=\"business\" scheme=\"all\">\n <button>Gestionale</button>\n <span>Editoriale</span>\n </mds-pref-theme>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Editoriale\" name=\"editorial\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Do Not Use an Invalid Theme Name\n\nThe `name` prop must match the pattern `^[a-z]+(-[a-z]+)*$` (lowercase letters and hyphens only). Any other value - including uppercase, underscores, or spaces - is ignored with a console warning when the component tries to apply the theme on `<html>`: the theme is neither applied nor stored.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-theme name=\"My Theme\" scheme=\"all\">...</mds-pref-theme>\n<mds-pref-theme name=\"my_theme\" scheme=\"all\">...</mds-pref-theme>\n<mds-pref-theme name=\"MyTheme\" scheme=\"all\">...</mds-pref-theme>\n\n<!-- CORRECT -->\n<mds-pref-theme name=\"editorial\" scheme=\"all\">...</mds-pref-theme>\n```\n\n#### Do Not Listen for the Native `change` Event\n\n`<mds-pref-theme>` emits `mdsPrefThemeChange` - a documented custom event with a typed `{ name, scheme }` detail. Listening for the native `change` event will not fire because theme selection is handled entirely inside shadow DOM.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelector('mds-pref-theme').addEventListener('change', (e) => {\n console.log(e.target.value); // undefined - wrong event, wrong detail shape\n });\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-pref-theme').addEventListener('mdsPrefThemeChange', (e) => {\n console.log(e.detail.name, e.detail.scheme);\n });\n</script>\n```\n\n#### Do Not Give the Parent and the Child Different Sizes\n\n`<mds-pref>` forwards its own `size` to all `mds-pref-*` children, on load and when it changes, and overwrites theirs: a `size` on `<mds-pref-theme>` that differs from the parent's is never shown. Set the size on the parent only.\n\n```html\n<!-- INCORRECT -->\n<mds-pref size=\"sm\">\n <mds-pref-theme size=\"md\" name=\"default\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref size=\"sm\">\n <mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n"
25061
+ "1. Description": "The `<mds-pref-theme>` web component is the theme-switcher segment of the Magma accessibility preferences panel, usually a direct child of [`<mds-pref>`](../mds-pref/AGENTS.md). It renders a labelled tab trigger that opens a dropdown of selectable named themes and, when a theme is chosen, applies it globally to the document.\n\n#### Semantic Behavior\n\n- **Usually inside `<mds-pref>`**: Placed as a direct slot child of `<mds-pref>`, alongside the other `mds-pref-*` controls; it also works on its own, since it applies and stores the theme by itself. What it gives up on its own is in its mistakes.\n- **Acts as a sub-parent itself**: Its own default slot must contain one or more `mds-pref-theme-item` elements; it drives their selected state so only the active theme is marked selected.\n- **Global theme application**: Selecting an item applies the theme document-wide: it writes `data-theme-name` and the `pref-theme-scheme-*` class on `<html>`.\n- **The theme's own mode**: A theme file can list the colour modes it can be used in (`color.modes`); a theme of one mode declares it in its block of `themes.css`, and the component applies the theme in that mode (`pref-theme-scheme-dark` or `-light`) whatever the item's `scheme` says. The stylesheet of the theme must be on the page when the theme is applied. The storage keeps the item's `scheme`.\n- **Persistence and hydration**: The current name, scheme and corner shape are persisted and restored across reloads: a stored value outranks the matching prop.\n- **Validation**: An invalid theme name (not lowercase kebab-case matching `^[a-z]+(-[a-z]+)*$`) is ignored with a console warning when the theme is applied: nothing is written on `<html>` or stored. So are the reserved names `light`, `dark` and `system` (they are mode values) and `scheme` or `scheme-*` (they would collide with the `pref-theme-scheme-*` classes), a `scheme` other than `light`, `dark` or `all`, and a `corner-shape` outside its keywords. A stored value the component cannot apply is dropped, and the prop is used instead.\n- **Events bubbled up**: Emits `mdsPrefThemeChange` with the `{ name, scheme }` detail on each pick, `scheme` being the one the theme is applied with (the theme's own mode, when it declares one). `<mds-pref-mode>` follows the scheme from `<html>`, with no listener. It also emits `mdsPrefChange` once per change, after applying it: `preference: 'theme'` for a new name or scheme, `'corner-shape'` for a new corner shape. The first application on load and a re-render that changes nothing do not emit it.\n- **Props set after load**: A `name`, `scheme` or `cornerShape` set from a script after load is stored and applied, as a pick is: the stored value outranks the prop only on load. A value the component would not apply is not stored.\n- **Localized label**: The \"Theme\" heading follows the active interface language.\n- **Trigger text**: The closed control shows the `label` of the item for the active theme, the same text the open list shows (localize the items, the trigger follows); when no item matches the active theme it shows the label derived from the name (`dark-blue` -> \"Dark blue\").\n\n#### Properties & Visual Configurations\n\n- **`name`**: The active theme name; it is overridden at runtime by any persisted value. Use it to declare the initial theme when no preference has been stored yet. The named themes are `business`, the base theme, and `editorial` ([`agents/theming.md`](../../../../agents/theming.md)). The default `'default'` is the old name of `business`, kept until the next major, when the default becomes `'business'`: the two names stand for the same theme, so with `name` left out the item `business` is the one marked, and an item named `default` is marked under `business`. `cool` and `warm` are deprecated.\n- **`scheme`**: Constrains the colour modes of the theme to `'light'`, `'dark'`, or `'all'` (default). Pick `'all'` for themes that ship both light and dark palettes; pick `'light'` or `'dark'` to force a single mode for a theme offered in one mode only. A theme that declares its own mode (`color.modes` in its file) needs no `scheme`: its declaration wins.\n- **`size`**: Sets the size (`'sm'` / `'md'`) of the nested tab UI. Inside `<mds-pref>`, set it on the parent: it reaches every `mds-pref-*` segment on load and when it changes, and overwrites the segment's own.\n- **`cornerShape`** (attribute `corner-shape`): The corner geometry of the whole page - `round`, `squircle`, `bevel`, `notch`, `scoop`, `square`, or `default`. It writes `data-corner-shape` on `<html>` and is persisted like the theme; `default` removes the attribute, and leaving the prop unset touches nothing ([`agents/theming.md`](../../../../agents/theming.md)).\n",
25062
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-pref-theme>` component, ordered from most common to most specialized. The examples assume a working knowledge of the preferences system documented in [`agents/theming.md`](../../../../agents/theming.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Theme Chooser\n\nThe canonical form. Place `<mds-pref-theme>` inside [`<mds-pref>`](../mds-pref/AGENTS.md) and populate its default slot with one [`<mds-pref-theme-item>`](../mds-pref-theme-item/AGENTS.md) per available theme. The item whose `name` matches the active theme (the stored choice, or the parent's `name` on a first visit) starts as selected. The named themes are `business`, the base theme of the management software, and `editorial`, the theme of the publishing side.\n\n```html\n<mds-pref>\n <mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Editoriale\" name=\"editorial\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Scheme-Constrained Themes\n\nA theme made for one colour mode says so in its file (`\"modes\": [\"dark\"]` in `color`), and the component applies it in that mode with no attribute on the item. For a theme whose file says nothing, use `scheme=\"light\"` or `scheme=\"dark\"` on a `<mds-pref-theme-item>`. Either way the component writes the scheme on `<html>` and forces that mode even if the user's OS or mode preference asks for the opposite, and `<mds-pref-mode>` shows that mode with its other items locked.\n\n```html\n<mds-pref>\n <mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n <!-- light only - dark mode will not activate with this item -->\n <mds-pref-theme-item label=\"Editoriale chiaro\" name=\"editorial\" scheme=\"light\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Listening for the Change Event\n\nReact to the user's selection via `mdsPrefThemeChange`. The event detail carries `{ name, scheme }` - use them to update any app-level state that tracks the active theme.\n\n```html\n<mds-pref>\n <mds-pref-theme id=\"theme-chooser\" name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Editoriale\" name=\"editorial\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n\n<script>\n document.querySelector('#theme-chooser').addEventListener('mdsPrefThemeChange', (e) => {\n console.log('Tema attivo:', e.detail.name, '- Schema:', e.detail.scheme);\n });\n</script>\n```\n\n#### Declaring the Initial Theme\n\nUse the `name` prop to declare which theme should be active before the user makes a selection. If `localStorage` already holds a persisted value it takes precedence; otherwise the component applies `name` on first render.\n\n```html\n<mds-pref>\n <!-- First-visit default is \"editorial\" -->\n <mds-pref-theme name=\"editorial\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Editoriale\" name=\"editorial\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Controlling Item Size\n\nPass `size=\"sm\"` when the preferences panel must fit a compact layout: on `<mds-pref>`, which forwards it to every preference control.\n\n```html\n<mds-pref size=\"sm\">\n <mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Editoriale\" name=\"editorial\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Styling Theme Items\n\nStyle theme items only through their public `--mds-pref-theme-item-*` CSS custom properties. Set them on the item host or on a parent selector; name a semantic role, `rgb(var(--magma-<role>))` ([`agents/color.md`](../../../../agents/color.md)), so the colours follow the mode, the theme and the contrast preference.\n\n```css\nmds-pref-theme-item {\n --mds-pref-theme-item-color-background: rgb(var(--magma-surface-inverse));\n}\n```\n",
25063
+ "3. Mistakes": "Common incorrect uses of `<mds-pref-theme>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind colour utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use the Component Outside `<mds-pref>`\n\n`<mds-pref-theme>` is a compound sub-part designed to slot inside [`<mds-pref>`](../mds-pref/AGENTS.md). As a standalone widget it still applies and persists the theme, but it leaves the panel: `<mds-pref>` can no longer forward `size` changes to it. The lock of a single-mode theme on `<mds-pref-mode>` holds either way.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n</mds-pref-theme>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Do Not Put Plain Text or Arbitrary HTML in the Default Slot\n\nThe default slot is reserved exclusively for `<mds-pref-theme-item>` elements. Any other content bypasses the component's internal selection management and will not trigger theme application.\n\n```html\n<!-- INCORRECT -->\n<mds-pref>\n <mds-pref-theme name=\"business\" scheme=\"all\">\n <button>Gestionale</button>\n <span>Editoriale</span>\n </mds-pref-theme>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Editoriale\" name=\"editorial\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Do Not Use an Invalid Theme Name\n\nThe `name` prop must match the pattern `^[a-z]+(-[a-z]+)*$` (lowercase letters and hyphens only). Any other value - including uppercase, underscores, or spaces - is ignored with a console warning when the component tries to apply the theme on `<html>`: the theme is neither applied nor stored.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-theme name=\"My Theme\" scheme=\"all\">...</mds-pref-theme>\n<mds-pref-theme name=\"my_theme\" scheme=\"all\">...</mds-pref-theme>\n<mds-pref-theme name=\"MyTheme\" scheme=\"all\">...</mds-pref-theme>\n\n<!-- CORRECT -->\n<mds-pref-theme name=\"editorial\" scheme=\"all\">...</mds-pref-theme>\n```\n\n#### Do Not Listen for the Native `change` Event\n\n`<mds-pref-theme>` emits `mdsPrefThemeChange` - a documented custom event with a typed `{ name, scheme }` detail. Listening for the native `change` event will not fire because theme selection is handled entirely inside shadow DOM.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelector('mds-pref-theme').addEventListener('change', (e) => {\n console.log(e.target.value); // undefined - wrong event, wrong detail shape\n });\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-pref-theme').addEventListener('mdsPrefThemeChange', (e) => {\n console.log(e.detail.name, e.detail.scheme);\n });\n</script>\n```\n\n#### Do Not Give the Parent and the Child Different Sizes\n\n`<mds-pref>` forwards its own `size` to all `mds-pref-*` children, on load and when it changes, and overwrites theirs: a `size` on `<mds-pref-theme>` that differs from the parent's is never shown. Set the size on the parent only.\n\n```html\n<!-- INCORRECT -->\n<mds-pref size=\"sm\">\n <mds-pref-theme size=\"md\" name=\"default\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref size=\"sm\">\n <mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item label=\"Gestionale\" name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n"
24530
25064
  },
24531
25065
  "props": [
24532
25066
  {
@@ -24638,7 +25172,7 @@
24638
25172
  "mutable": true,
24639
25173
  "attr": "scheme",
24640
25174
  "reflectToAttr": true,
24641
- "docs": "Specifies the theme scheme which can be 'light', 'dark' or 'all'\nDefault is 'all' which means this theme supporto both light and dark.\nIf you set 'light' means this theme support only light mode and will be forced and shown light colors mode only.",
25175
+ "docs": "Specifies the theme scheme which can be 'light', 'dark' or 'all'\nDefault is 'all' which means this theme supporto both light and dark.\nIf you set 'light' means this theme support only light mode and will be forced and shown light colors mode only.\nA theme whose stylesheet declares one mode (`--magma-color-modes`, from `color.modes` of its\nfile) is applied in that mode whatever this says: the theme's own lock wins.",
24642
25176
  "docsTags": [
24643
25177
  {
24644
25178
  "name": "default",
@@ -24745,7 +25279,7 @@
24745
25279
  },
24746
25280
  "cancelable": true,
24747
25281
  "composed": true,
24748
- "docs": "Emits when the component changes the language selected from the click event of the dropdown list item",
25282
+ "docs": "Emits when the component changes the language selected from the click event of the dropdown list item.\nIts `scheme` is the one the theme is applied with: the mode the theme declares, when it\ndeclares one, or else the scheme of the item.",
24749
25283
  "docsTags": []
24750
25284
  }
24751
25285
  ],
@@ -24783,8 +25317,8 @@
24783
25317
  "mds-button"
24784
25318
  ],
24785
25319
  "mds-button": [
24786
- "mds-spinner",
24787
25320
  "mds-icon",
25321
+ "mds-spinner",
24788
25322
  "mds-text"
24789
25323
  ]
24790
25324
  },
@@ -24803,7 +25337,7 @@
24803
25337
  }
24804
25338
  ],
24805
25339
  "usage": {
24806
- "1. Description": "The `<mds-pref-theme-item>` web component is a single selectable theme entry inside the [`<mds-pref-theme>`](../mds-pref-theme/AGENTS.md) preference picker. It renders as a borderless button that pairs a color-swatch preview of the theme with its label.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-pref-theme>`; it is not used standalone or mixed with other child component types.\n- **Selection is parent-driven**: On click each item emits `mdsPrefThemeItemSelect` (carrying `{ name, scheme }`), and the parent responds by clearing the siblings and selecting the clicked one. Setting `selected` directly on a single item does not coordinate the others.\n- **Click bubbles up**: The emitted event is what the parent listens to in order to apply the theme to the document and persist the choice.\n- **Auto-derived label**: If `label` is omitted, it is generated from `name` by capitalizing the first letter and replacing hyphens with spaces (e.g. `maggioli-editore` becomes `Maggioli editore`).\n- **Preview of the theme it names**: The preview background and the primary dot show the wash and the accent of the theme named by `name`, which the styles of that theme publish as `--magma-preview-<name>-wash` and `--magma-preview-<name>-accent` (`themes.css` does for every theme Magma ships), so each item of the picker shows its own theme whatever the active one. The success, warning and error dots are the page's status emphases, which no theme retints. A theme that publishes no preview shows the active theme. The `--mds-pref-theme-item-*` CSS custom properties paint all of it and still override it.\n\n#### Properties & Visual Configurations\n\n- **`name`**: The theme identifier reported to the parent and matched against the parent's active `name` to compute initial selection. Use a simple or kebab-case string; the named themes are `business`, the base theme, and `editorial` ([`agents/theming.md`](../../../../agents/theming.md)). `default`, `cool` and `warm` still work and are deprecated: they leave at the next major. The parent validates the lowercase/kebab format and ignores an invalid name with a console warning.\n- **`scheme`**: Declares which color schemes the theme supports - `all` (default, both light and dark), or `light` / `dark` to force a single mode. This value travels with the selection event and is applied by the parent when the item is chosen.\n- **`selected`**: Reflects whether this item is the active theme. The parent sets it on every item when it loads and on each pick, so a value set by hand is overwritten.\n",
25340
+ "1. Description": "The `<mds-pref-theme-item>` web component is a single selectable theme entry inside the [`<mds-pref-theme>`](../mds-pref-theme/AGENTS.md) preference picker. It renders as a borderless button that pairs a color-swatch preview of the theme with its label.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-pref-theme>`; it is not used standalone or mixed with other child component types.\n- **Selection is parent-driven**: On click each item emits `mdsPrefThemeItemSelect` (carrying `{ name, scheme }`), and the parent responds by clearing the siblings and selecting the clicked one. Setting `selected` directly on a single item does not coordinate the others.\n- **Click bubbles up**: The emitted event is what the parent listens to in order to apply the theme to the document and persist the choice.\n- **Auto-derived label**: If `label` is omitted, it is generated from `name` by capitalizing the first letter and replacing hyphens with spaces (e.g. `maggioli-editore` becomes `Maggioli editore`).\n- **Preview of the theme it names**: The preview background and the primary dot show the wash and the accent of the theme named by `name`, which the styles of that theme publish as `--magma-preview-<name>-wash` and `--magma-preview-<name>-accent` (`themes.css` does for every theme Magma ships), so each item of the picker shows its own theme whatever the active one. The success, warning and error dots are the page's status emphases, which no theme retints. A theme that publishes no preview shows the active theme. The `--mds-pref-theme-item-*` CSS custom properties paint all of it and still override it.\n\n#### Properties & Visual Configurations\n\n- **`name`**: The theme identifier reported to the parent and matched against the parent's active `name` to compute initial selection. Use a simple or kebab-case string; the named themes are `business`, the base theme, and `editorial` ([`agents/theming.md`](../../../../agents/theming.md)). `default`, `cool` and `warm` still work and are deprecated: they leave at the next major. The parent validates the lowercase/kebab format and ignores an invalid name with a console warning.\n- **`scheme`**: Declares which color schemes the theme supports - `all` (default, both light and dark), or `light` / `dark` to force a single mode. This value travels with the selection event and is applied by the parent when the item is chosen, unless the theme declares its own mode in its stylesheet (`color.modes` of its file), which wins.\n- **`selected`**: Reflects whether this item is the active theme. The parent sets it on every item when it loads and on each pick, so a value set by hand is overwritten.\n",
24807
25341
  "2. Examples": "Correct and idiomatic ways to use the `<mds-pref-theme-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Usage Inside the Parent\n\n`<mds-pref-theme-item>` must always be a direct child of [`<mds-pref-theme>`](../mds-pref-theme/AGENTS.md). Each item represents one selectable colour theme; the parent manages selection state so all siblings stay in sync.\n\n```html\n<mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item name=\"business\" label=\"Gestionale\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"editorial\" label=\"Editoriale\" scheme=\"all\"></mds-pref-theme-item>\n</mds-pref-theme>\n```\n\n#### Auto-Derived Label\n\nOmit `label` and let the component generate it from `name`: the first letter is capitalised and hyphens are replaced with spaces. Use this shorthand when the theme name is already human-readable.\n\n```html\n<mds-pref-theme name=\"business\" scheme=\"all\">\n <!-- renders \"Business\" and \"Editorial\" without explicit label props -->\n <mds-pref-theme-item name=\"business\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"editorial\" scheme=\"all\"></mds-pref-theme-item>\n</mds-pref-theme>\n```\n\n#### Scheme-Specific Themes\n\nSet `scheme` to `\"light\"` or `\"dark\"` when a theme must be offered in a single colour mode only. The parent applies the forced mode when the item is selected.\n\n```html\n<mds-pref-theme name=\"business\" scheme=\"all\">\n <!-- this theme works in both modes -->\n <mds-pref-theme-item name=\"business\" label=\"Gestionale\" scheme=\"all\"></mds-pref-theme-item>\n\n <!-- offered light-only; selecting it locks the UI in light mode -->\n <mds-pref-theme-item name=\"editorial\" label=\"Editoriale chiaro\" scheme=\"light\"></mds-pref-theme-item>\n</mds-pref-theme>\n```\n\n#### Listening to the Selection Event\n\nAttach a listener for `mdsPrefThemeItemSelect` when you need to react to a selection at the item level - for example to log analytics. The detail carries `{ name, scheme }`. Normally the parent handles theme application automatically; only listen at this level for side-effects.\n\n```html\n<mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item name=\"business\" label=\"Gestionale\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"editorial\" label=\"Editoriale\" scheme=\"all\"></mds-pref-theme-item>\n</mds-pref-theme>\n\n<script>\n document.querySelectorAll('mds-pref-theme-item').forEach((item) => {\n item.addEventListener('mdsPrefThemeItemSelect', (e) => {\n console.log('Tema selezionato:', e.detail.name, 'schema:', e.detail.scheme);\n });\n });\n</script>\n```\n\n#### Setting the Initially Selected Item\n\nDeclare it on the parent, not with `selected`: when it loads, `<mds-pref-theme>` marks the item whose `name` matches the active theme (the stored choice, or its own `name` on a first visit) and overwrites any `selected` written in the markup.\n\n```html\n<mds-pref-theme name=\"editorial\" scheme=\"all\">\n <mds-pref-theme-item name=\"business\" label=\"Gestionale\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"editorial\" label=\"Editoriale\" scheme=\"all\"></mds-pref-theme-item>\n</mds-pref-theme>\n```\n\n#### CSS Customization via Documented Properties\n\nOverride the swatch only through the public `--mds-pref-theme-item-color-background` CSS custom property, the background behind the preview dots; the dots themselves are painted by the component. Set it on the host element or a parent selector and name a semantic role for the colour value, `rgb(var(--magma-<role>))` ([`agents/color.md`](../../../../agents/color.md)), so mode, theme and contrast keep working. It replaces the preview of the theme the item names.\n\n```css\n/* override the swatch background of one theme item */\nmds-pref-theme-item[name=\"editorial\"] {\n --mds-pref-theme-item-color-background: rgb(var(--magma-wash-strong));\n}\n```\n",
24808
25342
  "3. Mistakes": "Common incorrect uses of `<mds-pref-theme-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use the Item Outside Its Parent\n\n`<mds-pref-theme-item>` is a compound child that must be a direct slot child of [`<mds-pref-theme>`](../mds-pref-theme/AGENTS.md). Used standalone it emits selection events that are never handled, and it never receives coordinated deselection of siblings.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-theme-item name=\"editorial\" label=\"Editoriale\" scheme=\"all\"></mds-pref-theme-item>\n\n<!-- CORRECT -->\n<mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item name=\"editorial\" label=\"Editoriale\" scheme=\"all\"></mds-pref-theme-item>\n</mds-pref-theme>\n```\n\n#### Do Not Set `selected` Manually to Coordinate Multi-Item State\n\nSetting `selected` on one item does not deselect the others - the parent is the only actor that can coordinate the whole group. When it loads it marks only the item matching the active theme, overwriting the `selected` in the markup; a value set later from script leaves several items marked. Drive initial selection through the parent's `name` prop or by letting the user click.\n\n```html\n<!-- INCORRECT - the parent overwrites both on load and marks \"default\" -->\n<mds-pref-theme name=\"business\" scheme=\"all\">\n <mds-pref-theme-item name=\"business\" label=\"Gestionale\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"editorial\" label=\"Editoriale\" scheme=\"all\" selected></mds-pref-theme-item>\n</mds-pref-theme>\n\n<!-- CORRECT - set the active theme on the parent; it marks the matching child -->\n<mds-pref-theme name=\"editorial\" scheme=\"all\">\n <mds-pref-theme-item name=\"business\" label=\"Gestionale\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"editorial\" label=\"Editoriale\" scheme=\"all\"></mds-pref-theme-item>\n</mds-pref-theme>\n```\n\n#### Do Not Listen for Native `click` Instead of the Component Event\n\nA raw `click` carries no `detail`: you have to read `name` back from the element, and you lose the `scheme`. Listen for the documented `mdsPrefThemeItemSelect` event instead, whose detail carries `{ name, scheme }`.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelector('mds-pref-theme-item').addEventListener('click', (e) => {\n applyTheme(e.target.getAttribute('name'));\n });\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-pref-theme-item').addEventListener('mdsPrefThemeItemSelect', (e) => {\n applyTheme(e.detail.name);\n });\n</script>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Inner Button\n\nThe supported customization surface is the public `--mds-pref-theme-item-color-background` CSS custom property. Targeting internal selectors or `::part()` names not present in this component's public API couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-pref-theme-item >>> mds-button {\n font-weight: bold;\n}\nmds-pref-theme-item .theme-preview {\n border: 2px solid red;\n}\n\n/* CORRECT */\nmds-pref-theme-item[name=\"editorial\"] {\n --mds-pref-theme-item-color-background: rgb(var(--magma-wash-strong));\n}\n```\n\n#### Do Not Use an Invalid `scheme` Value\n\n`scheme` only accepts `\"all\"`, `\"light\"`, or `\"dark\"`. Other strings are ignored by the parent with a console warning: picking the item applies and stores nothing, so the theme does not change at all.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-theme-item name=\"editorial\" scheme=\"light-only\"></mds-pref-theme-item>\n<mds-pref-theme-item name=\"business\" scheme=\"night\"></mds-pref-theme-item>\n\n<!-- CORRECT -->\n<mds-pref-theme-item name=\"editorial\" scheme=\"light\"></mds-pref-theme-item>\n<mds-pref-theme-item name=\"business\" scheme=\"dark\"></mds-pref-theme-item>\n```\n"
24809
25343
  },
@@ -25017,8 +25551,8 @@
25017
25551
  "mds-button"
25018
25552
  ],
25019
25553
  "mds-button": [
25020
- "mds-spinner",
25021
25554
  "mds-icon",
25555
+ "mds-spinner",
25022
25556
  "mds-text"
25023
25557
  ]
25024
25558
  },
@@ -26344,8 +26878,8 @@
26344
26878
  "mds-button"
26345
26879
  ],
26346
26880
  "mds-button": [
26347
- "mds-spinner",
26348
26881
  "mds-icon",
26882
+ "mds-spinner",
26349
26883
  "mds-text"
26350
26884
  ]
26351
26885
  },
@@ -26969,8 +27503,8 @@
26969
27503
  "mds-button"
26970
27504
  ],
26971
27505
  "mds-button": [
26972
- "mds-spinner",
26973
27506
  "mds-icon",
27507
+ "mds-spinner",
26974
27508
  "mds-text"
26975
27509
  ]
26976
27510
  },
@@ -27716,8 +28250,8 @@
27716
28250
  "mds-button"
27717
28251
  ],
27718
28252
  "mds-button": [
27719
- "mds-spinner",
27720
28253
  "mds-icon",
28254
+ "mds-spinner",
27721
28255
  "mds-text"
27722
28256
  ]
27723
28257
  },
@@ -28006,8 +28540,8 @@
28006
28540
  "mds-tooltip"
28007
28541
  ],
28008
28542
  "mds-button": [
28009
- "mds-spinner",
28010
28543
  "mds-icon",
28544
+ "mds-spinner",
28011
28545
  "mds-text"
28012
28546
  ],
28013
28547
  "mds-tooltip": [
@@ -28656,8 +29190,8 @@
28656
29190
  "mds-button"
28657
29191
  ],
28658
29192
  "mds-button": [
28659
- "mds-spinner",
28660
29193
  "mds-icon",
29194
+ "mds-spinner",
28661
29195
  "mds-text"
28662
29196
  ]
28663
29197
  },
@@ -28887,7 +29421,7 @@
28887
29421
  ],
28888
29422
  "usage": {
28889
29423
  "1. Description": "The `<mds-stepper-bar-item>` web component represents a single step inside a [`<mds-stepper-bar>`](../mds-stepper-bar/AGENTS.md) progress indicator, rendering the step's icon, optional ordinal label, descriptive text and status badge. It has no standalone meaning: it is the unit the parent stepper orchestrates to express a sequential, multi-step flow.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-stepper-bar>`; it is not used standalone or mixed with other child types in that slot.\n- **State driven by the parent**: The `done` and `current` props are not set per item by the consumer - the parent's `itemsDone` prop drives `done`/`current` on each child, so an item's visual state is a function of its position relative to the active step.\n- **Index resolution**: The item computes its own ordinal from its position among the parent's children; this index feeds the localized \"step N\" caption rendered when `step` is enabled.\n- **Three-way status badge**: When `badge` is true the item renders a status badge whose variant and localized text reflect the resolved state - `success`/done, `info`/current, or `dark`/queued.\n- **Icon swap on completion**: The displayed icon switches from `icon` to `iconChecked` once the item is done and no longer current.\n- **Going back**: A step that is done (and not current) is a button in the tab order: a click or Enter emits `mdsStepperBarItemDone` with its `{ value }`. It asks, it does not move: the page goes back by setting `itemsDone` on the bar. The current and the following steps are not interactive.\n- **Localization**: Step, badge and status strings are localized (el/en/es/it).\n\n#### Properties & Visual Configurations\n\nMost state props are managed by the parent rather than the consumer. The props worth configuring directly on each item are:\n\n- **`icon` / `iconChecked`**: Set `icon` for the default and current appearance; set `iconChecked` only when the completed step should show a different glyph (it defaults to `icon`).\n- **`step`**: Enable to surface the auto-numbered \"step N\" caption above the label - use it for explicitly ordered flows where the number aids orientation.\n- **`badge`**: Enable to show the queued/current/done status pill; prefer it when status legibility matters more than horizontal compactness.\n- **`value`**: The token the parent collects from the completed items into the `value` of its `mdsStepperBarChange` detail (comma-joined); set it so the parent can aggregate which steps have been completed.\n- **`typography`**: Overrides the label's typography token (defaults to `h6`); lower it for denser bars.\n",
28890
- "2. Examples": "Correct and idiomatic ways to use the `<mds-stepper-bar-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Minimal Step Inside a Stepper Bar\n\nPlace `<mds-stepper-bar-item>` elements as direct children of [`<mds-stepper-bar>`](../mds-stepper-bar/AGENTS.md). Each item requires `label` and `icon`. `items-done` on the parent drives the `done` and `current` state of each child automatically.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n icon=\"mi/baseline/person\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/location-on\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Distinct Icon for the Completed State\n\nSet `icon-checked` to a different slug when the done state should show a different glyph - for example a checkmark. When omitted, `icon-checked` defaults to `icon`.\n\n```html\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Showing the Ordinal Caption with `step`\n\nSet the boolean `step` attribute to surface an auto-numbered \"Step N\" caption above the label. Use this for explicitly ordered flows where the ordinal number aids orientation.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Status Badge via `badge`\n\nSet `badge` to show the localized status pill (Completato / In corso / In coda). Prefer this when status legibility matters more than horizontal compactness.\n\n```html\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Carrying a Value for Event Handling\n\nSet `value` on each item: the parent collects the values of the completed items, comma-joined, into the `value` of its `mdsStepperBarChange` detail. Listen to that event on the parent or a common ancestor.\n\n```html\n<mds-stepper-bar id=\"stepper\" items-done=\"1\">\n <mds-stepper-bar-item\n value=\"dati-personali\"\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n value=\"indirizzo\"\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n value=\"pagamento\"\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n\n<script>\n document.getElementById('stepper').addEventListener('mdsStepperBarChange', (e) => {\n console.log('step completati:', e.detail.value, 'step corrente:', e.detail.step);\n });\n</script>\n```\n\n#### Pairing Step Content via the `content` Slot\n\nPlace panel elements with `slot=\"content\"` inside `<mds-stepper-bar>` - one per item in order. The parent shows only the panel matching the current step (it puts the `hidden` attribute on the others, so no style of the page is needed; a `display` the page sets on a panel overrides it).\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/payment\" label=\"Pagamento\"></mds-stepper-bar-item>\n\n <div slot=\"content\">\n <p>Inserisci il tuo nome e cognome.</p>\n </div>\n <div slot=\"content\">\n <p>Inserisci il tuo indirizzo di spedizione.</p>\n </div>\n <div slot=\"content\">\n <p>Scegli il metodo di pagamento.</p>\n </div>\n</mds-stepper-bar>\n```\n\n#### Reducing Label Typography for Dense Bars\n\nLower the `typography` prop (default `h6`) when horizontal space is tight or when the label must blend with smaller surrounding text.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Styling Customization\n\nStyle items only through the public `--mds-stepper-bar-item-*` CSS custom properties: the text colour and the minimum width. The icon and progress colours follow the state the parent sets (queued, current, done) and are not set by the page. Use semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working. Target the `::part(badge)` surface only when a deep visual override of the badge wrapper is required.\n\n```css\n.checkout-flow mds-stepper-bar-item {\n --mds-stepper-bar-item-color: rgb(var(--magma-text-muted));\n --mds-stepper-bar-item-min-width: 160px;\n}\n```\n",
29424
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-stepper-bar-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Minimal Step Inside a Stepper Bar\n\nPlace `<mds-stepper-bar-item>` elements as direct children of [`<mds-stepper-bar>`](../mds-stepper-bar/AGENTS.md). Each item requires `label` and `icon`. `items-done` on the parent drives the `done` and `current` state of each child automatically.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n icon=\"mi/baseline/person\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/location-on\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Distinct Icon for the Completed State\n\nSet `icon-checked` to a different slug when the done state should show a different glyph - for example a checkmark. When omitted, `icon-checked` defaults to `icon`.\n\n```html\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Showing the Ordinal Caption with `step`\n\nSet the boolean `step` attribute to surface an auto-numbered \"Step N\" caption above the label. Use this for explicitly ordered flows where the ordinal number aids orientation.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Status Badge via `badge`\n\nSet `badge` to show the localized status pill (Completato / In corso / In coda). Prefer this when status legibility matters more than horizontal compactness.\n\n```html\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Carrying a Value for Event Handling\n\nSet `value` on each item: the parent collects the values of the completed items, comma-joined, into the `value` of its `mdsStepperBarChange` detail. Listen to that event on the parent or a common ancestor.\n\n```html\n<mds-stepper-bar id=\"stepper\" items-done=\"1\">\n <mds-stepper-bar-item\n value=\"dati-personali\"\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n value=\"indirizzo\"\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n value=\"pagamento\"\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n\n<script>\n document.getElementById('stepper').addEventListener('mdsStepperBarChange', (e) => {\n console.log('step completati:', e.detail.value, 'step corrente:', e.detail.step);\n });\n</script>\n```\n\n#### Pairing Step Content via the `content` Slot\n\nPlace panel elements with `slot=\"content\"` inside `<mds-stepper-bar>` - one per item in order. The parent shows only the panel matching the current step (it puts the `hidden` attribute on the others, so no style of the page is needed; a `display` the page sets on a panel overrides it).\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/payment\" label=\"Pagamento\"></mds-stepper-bar-item>\n\n <div slot=\"content\">\n <p>Inserisci il tuo nome e cognome.</p>\n </div>\n <div slot=\"content\">\n <p>Inserisci il tuo indirizzo di spedizione.</p>\n </div>\n <div slot=\"content\">\n <p>Scegli il metodo di pagamento.</p>\n </div>\n</mds-stepper-bar>\n```\n\n#### Reducing Label Typography for Dense Bars\n\nLower the `typography` prop (default `h6`) when horizontal space is tight or when the label must blend with smaller surrounding text.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Styling Customization\n\nStyle items only through the public `--mds-stepper-bar-item-*` CSS custom properties: the text colour and the minimum width. The minimum width applies to every item but the last: the last one draws no bar after its icon, so it takes the width of its texts and the bars of the others fill the rest of the row. The icon and progress colours follow the state the parent sets (queued, current, done) and are not set by the page. Use semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working. Target the `::part(badge)` surface only when a deep visual override of the badge wrapper is required.\n\n```css\n.checkout-flow mds-stepper-bar-item {\n --mds-stepper-bar-item-color: rgb(var(--magma-text-muted));\n --mds-stepper-bar-item-min-width: 160px;\n}\n```\n",
28891
29425
  "3. Mistakes": "Common incorrect uses of `<mds-stepper-bar-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use Outside `<mds-stepper-bar>`\n\n`<mds-stepper-bar-item>` is a compound child - its state (`done`, `current`, index) is resolved by the parent. Using it standalone leaves `isDone`, `isCurrent` and `index` at their defaults and produces broken visual output.\n\n```html\n<!-- INCORRECT -->\n<mds-stepper-bar-item icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n\n<!-- CORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Do Not Set `done=\"false\"` or `current=\"false\"` as Strings\n\n`done` and `current` are boolean props. Stencil reads `\"false\"` as `false` and, since both are reflected, removes the attribute at the first render, so this happens to work; but the markup says the opposite of what it does, and on a prop that is not reflected the attribute stays in the DOM, where `[attr]` selectors still match it. To turn them off, remove the attribute or let the parent manage state via `items-done`.\n\n```html\n<!-- INCORRECT -->\n<mds-stepper-bar-item done=\"false\" current=\"false\" icon=\"mi/baseline/payment\" label=\"Pagamento\"></mds-stepper-bar-item>\n\n<!-- CORRECT -->\n<mds-stepper-bar-item icon=\"mi/baseline/payment\" label=\"Pagamento\"></mds-stepper-bar-item>\n```\n\n#### Do Not Override State Manually When the Parent Manages It\n\n`done` and `current` are driven by `<mds-stepper-bar>`'s `items-done` prop. Setting them on individual items and also setting `items-done` creates conflicting state that the parent overwrites when it loads and whenever `items-done` changes.\n\n```html\n<!-- INCORRECT -->\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item done current icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n\n<!-- CORRECT -->\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Do Not Wrap Items in Extra HTML Elements\n\nEach item numbers itself among its own siblings, and the parent's track lays out its direct children: a wrapper `<div>` or `<li>` turns every wrapped item into \"Step 1\" and breaks the track layout and scroll alignment.\n\n```html\n<!-- INCORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <div>\n <mds-stepper-bar-item icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n </div>\n <div>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" label=\"Indirizzo\"></mds-stepper-bar-item>\n </div>\n</mds-stepper-bar>\n\n<!-- CORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Do Not Use Undocumented `::part()` Targets to Style the Icon or Progress\n\nThe only documented shadow part is `badge`. Targeting internals such as `::part(icon)` or `::part(progress)` couples code to the private Shadow DOM structure and will break on minor releases. The icon and the progress line take their colours from the step state; style the item through its public `--mds-stepper-bar-item-*` CSS custom properties instead.\n\n```css\n/* INCORRECT */\nmds-stepper-bar-item::part(icon) {\n background-color: purple;\n}\nmds-stepper-bar-item::part(progress) {\n height: 6px;\n}\n\n/* CORRECT */\nmds-stepper-bar-item {\n --mds-stepper-bar-item-color: rgb(var(--magma-text-default));\n --mds-stepper-bar-item-min-width: 160px;\n}\n```\n\n#### Do Not Omit `label` or `icon`\n\nBoth are required props. An item without `label` has no accessible or visual description; an item without `icon` leaves the icon area empty and breaks the progress-line layout.\n\n```html\n<!-- INCORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n\n<!-- CORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n"
28892
29426
  },
28893
29427
  "props": [
@@ -29273,7 +29807,7 @@
29273
29807
  {
29274
29808
  "name": "--mds-stepper-bar-item-min-width",
29275
29809
  "annotation": "prop",
29276
- "docs": "Sets the minimum width of the component",
29810
+ "docs": "Sets the minimum width of the component; the last item, which has no bar, takes the width of its texts instead",
29277
29811
  "visibility": "public"
29278
29812
  },
29279
29813
  {
@@ -29363,7 +29897,7 @@
29363
29897
  }
29364
29898
  ],
29365
29899
  "usage": {
29366
- "1. Description": "The `<mds-tab>` web component is the compound container that orchestrates a tabbed navigation in the Magma Design System. It is the parent wrapper around a set of `<mds-tab-item>` triggers and, when the component shows the content itself, their content panels, providing the ARIA `tablist` structure, selection state, scrolling and the animated selection indicator.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects `<mds-tab-item>` elements in the default slot; each panel in the named `content` slot is wired up automatically and paired by document order; a panel past the last item has no tab to open it, so it stays hidden and the component logs a console warning. The panels are optional: without them the component shows the strip alone, and the page shows the content, driven by `mdsTabChange` or by navigation.\n- **Navigation strip**: When every item has `href`, the items are links (announced as such, the selected one as current) and the strip is no longer a `tablist`: the browser follows the links, in a new tab on a modifier or middle click, and the strip keeps the selected item highlighted. A client-side router cancels the click on the item with `preventDefault()` and routes; a modifier click leaves the selection alone.\n- **Selection ownership**: The active tab is whichever `<mds-tab-item>` carries `selected`; the parent flips `selected` across siblings, shows the corresponding content panel and hides the rest.\n- **Change event**: Emits `mdsTabChange` with the selected item's index (`id`) and `value` whenever the active child changes.\n- **Focus restoration**: After a keyboard activation it re-focuses the selected item's button, so the user does not have to re-locate the tab.\n- **Auto-scroll into view**: On selection or child focus, the active tab is scrolled to the center of its strip.\n- **Overflow tracking**: When `overflow` is enabled, left/right inset shadows appear while the tabs overflow their container.\n- **Size propagation**: The parent `size` is pushed down onto every nested `<mds-tab-item>`, so children should not be sized individually.\n\n#### Properties & Visual Configurations\n\n- **`direction`** chooses whether the tab strip is laid out `'horizontal'` (default) or `'vertical'`.\n- **`animation`** governs the transition between active items: `'slide'` (default) renders the moving slider indicator, while `'fade'` cross-fades without the slider. The slider slides only when the selection changes: on load, and when the strip is shown again after being hidden, it is already under the selected tab.\n- **`fill`** makes the tab strip stretch to occupy the full available width rather than hugging its content.\n- **`overflow`** enables the inset-shadow affordance that signals more tabs exist beyond the visible edges; **`scrollbar`** instead exposes the native horizontal scrollbar for accessibility.\n\n#### Other behavioral props\n\n- **`size`** sets the scale (`'sm'` / `'md'`) for the whole group and is forwarded to the child items; it is the only way to size the tabs consistently.\n",
29900
+ "1. Description": "The `<mds-tab>` web component is the compound container that orchestrates a tabbed navigation in the Magma Design System. It is the parent wrapper around a set of `<mds-tab-item>` triggers and, when the component shows the content itself, their content panels, providing the ARIA `tablist` structure, selection state, scrolling and the animated selection indicator.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects `<mds-tab-item>` elements in the default slot; each panel in the named `content` slot is wired up automatically and paired by document order; a panel past the last item has no tab to open it, so it stays hidden and the component logs a console warning. The panels are optional: without them the component shows the strip alone, and the page shows the content, driven by `mdsTabChange` or by navigation.\n- **Navigation strip**: When every item has `href`, the items are links (announced as such, the selected one as current) and the strip is no longer a `tablist`: the browser follows the links, in a new tab on a modifier or middle click, and the strip keeps the selected item highlighted. A client-side router cancels the click on the item with `preventDefault()` and routes; a modifier click leaves the selection alone.\n- **Selection ownership**: The active tab is whichever `<mds-tab-item>` carries `selected`; the parent flips `selected` across siblings, shows the corresponding content panel and hides the rest.\n- **Change event**: Emits `mdsTabChange` with the selected item's index (`id`) and `value` whenever the active child changes.\n- **Focus restoration**: After a keyboard activation it re-focuses the selected item's button, so the user does not have to re-locate the tab. An item selected from code (`selected` set by the page) leaves the focus where it is.\n- **Auto-scroll into view**: On selection or child focus, the active tab is scrolled to the center of its strip.\n- **Overflow tracking**: When `overflow` is enabled, left/right inset shadows appear while the tabs overflow their container.\n- **Size propagation**: The parent `size` is pushed down onto every nested `<mds-tab-item>`, so children should not be sized individually.\n\n#### Properties & Visual Configurations\n\n- **`direction`** chooses whether the tab strip is laid out `'horizontal'` (default) or `'vertical'`.\n- **`animation`** governs the transition between active items: `'slide'` (default) renders the moving slider indicator, while `'fade'` cross-fades without the slider. The slider slides only when the selection changes: on load, and when the strip is shown again after being hidden, it is already under the selected tab.\n- **`fill`** makes the tab strip stretch to occupy the full available width rather than hugging its content.\n- **`overflow`** enables the inset-shadow affordance that signals more tabs exist beyond the visible edges; **`scrollbar`** instead exposes the native horizontal scrollbar for accessibility.\n\n#### Other behavioral props\n\n- **`size`** sets the scale (`'sm'` / `'md'`) for the whole group and is forwarded to the child items; it is the only way to size the tabs consistently.\n",
29367
29901
  "2. Examples": "Correct and idiomatic ways to use the `<mds-tab>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Tab Group with Managed Panels\n\nThe canonical form. Put `<mds-tab-item>` elements in the default slot and one content element per tab in the named `content` slot. Mark the initially-visible tab with `selected`. Panels are wired up by document order - the first `[slot=content]` element is paired with the first `<mds-tab-item>`.\n\n```html\n<mds-tab>\n <mds-tab-item label=\"Panoramica\" selected></mds-tab-item>\n <mds-tab-item label=\"Dettagli\"></mds-tab-item>\n <mds-tab-item label=\"Allegati\"></mds-tab-item>\n\n <div slot=\"content\">\n <mds-text>Contenuto della scheda Panoramica.</mds-text>\n </div>\n <div slot=\"content\">\n <mds-text>Contenuto della scheda Dettagli.</mds-text>\n </div>\n <div slot=\"content\">\n <mds-text>Contenuto della scheda Allegati.</mds-text>\n </div>\n</mds-tab>\n```\n\n#### Listening to Tab Changes\n\nListen to the `mdsTabChange` event to react when the active panel changes. The event detail carries the zero-based `id` (index) and the optional `value` of the newly selected `<mds-tab-item>`.\n\n```html\n<mds-tab id=\"schede-pratica\">\n <mds-tab-item label=\"Anagrafica\" value=\"anagrafica\" selected></mds-tab-item>\n <mds-tab-item label=\"Documenti\" value=\"documenti\"></mds-tab-item>\n <mds-tab-item label=\"Pagamenti\" value=\"pagamenti\"></mds-tab-item>\n</mds-tab>\n\n<script>\n document.querySelector('#schede-pratica').addEventListener('mdsTabChange', (e) => {\n console.log('scheda attiva:', e.detail.id, e.detail.value);\n });\n</script>\n```\n\n#### Tab Items with Icons\n\nPass an icon slug to `<mds-tab-item>` via the `icon` prop. Icon position defaults to `left`; use `icon-position=\"right\"` for forward-navigation tabs.\n\n```html\n<mds-tab>\n <mds-tab-item label=\"Utente\" icon=\"mi/baseline/person\" selected></mds-tab-item>\n <mds-tab-item label=\"Impostazioni\" icon=\"mi/baseline/settings\"></mds-tab-item>\n <mds-tab-item label=\"Notifiche\" icon=\"mi/baseline/notifications\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Profilo utente.</mds-text></div>\n <div slot=\"content\"><mds-text>Impostazioni account.</mds-text></div>\n <div slot=\"content\"><mds-text>Cronologia notifiche.</mds-text></div>\n</mds-tab>\n```\n\n#### Fill the Available Width\n\nSet `fill` when the tab strip should stretch to occupy the full container width instead of hugging its content.\n\n```html\n<mds-tab fill>\n <mds-tab-item label=\"Riepilogo\" selected></mds-tab-item>\n <mds-tab-item label=\"Cronologia\"></mds-tab-item>\n <mds-tab-item label=\"Statistiche\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Riepilogo pratica.</mds-text></div>\n <div slot=\"content\"><mds-text>Registro modifiche.</mds-text></div>\n <div slot=\"content\"><mds-text>Dati statistici.</mds-text></div>\n</mds-tab>\n```\n\n#### Vertical Direction\n\nUse `direction=\"vertical\"` to stack the tab strip on the side. Pair it with `--mds-tab-direction-vertical-columns` to control the column widths of the sidebar and the content area.\n\n```html\n<mds-tab direction=\"vertical\">\n <mds-tab-item label=\"Dati generali\" selected></mds-tab-item>\n <mds-tab-item label=\"Indirizzi\"></mds-tab-item>\n <mds-tab-item label=\"Contatti\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Dati generali.</mds-text></div>\n <div slot=\"content\"><mds-text>Indirizzi registrati.</mds-text></div>\n <div slot=\"content\"><mds-text>Recapiti di contatto.</mds-text></div>\n</mds-tab>\n```\n\n#### Fade Animation\n\nSwitch to `animation=\"fade\"` to highlight the selected tab in place instead of moving the slider indicator. The panels switch without animation in both modes.\n\n```html\n<mds-tab animation=\"fade\">\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n <mds-tab-item label=\"Seconda\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Pannello 1.</mds-text></div>\n <div slot=\"content\"><mds-text>Pannello 2.</mds-text></div>\n</mds-tab>\n```\n\n#### Overflow Shadow for Many Tabs\n\nEnable `overflow` when the tab strip can contain more items than the viewport permits. Left and right inset shadows appear whenever tabs overflow their container, signalling that scrolling is possible.\n\n```html\n<mds-tab overflow>\n <mds-tab-item label=\"Gennaio\" selected></mds-tab-item>\n <mds-tab-item label=\"Febbraio\"></mds-tab-item>\n <mds-tab-item label=\"Marzo\"></mds-tab-item>\n <mds-tab-item label=\"Aprile\"></mds-tab-item>\n <mds-tab-item label=\"Maggio\"></mds-tab-item>\n <mds-tab-item label=\"Giugno\"></mds-tab-item>\n <mds-tab-item label=\"Luglio\"></mds-tab-item>\n <mds-tab-item label=\"Agosto\"></mds-tab-item>\n <mds-tab-item label=\"Settembre\"></mds-tab-item>\n <mds-tab-item label=\"Ottobre\"></mds-tab-item>\n <mds-tab-item label=\"Novembre\"></mds-tab-item>\n <mds-tab-item label=\"Dicembre\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Scrollbar for Accessible Overflow\n\nUse `scrollbar` instead of (or alongside) `overflow` to expose the native horizontal scrollbar. This is the accessible complement for users who navigate via keyboard or who have motor difficulties.\n\n```html\n<mds-tab scrollbar overflow>\n <mds-tab-item label=\"Sezione A\" selected></mds-tab-item>\n <mds-tab-item label=\"Sezione B\"></mds-tab-item>\n <mds-tab-item label=\"Sezione C\"></mds-tab-item>\n <mds-tab-item label=\"Sezione D\"></mds-tab-item>\n <mds-tab-item label=\"Sezione E\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Sizing\n\nSet `size` on the parent to scale all tabs uniformly. Do not set `size` on individual `<mds-tab-item>` elements - the parent propagates the value automatically.\n\n```html\n<!-- Compact strip, e.g. inside a sidebar or dense toolbar -->\n<mds-tab size=\"sm\">\n <mds-tab-item label=\"Vista elenco\" selected></mds-tab-item>\n <mds-tab-item label=\"Vista griglia\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Navigation Links (href on Tab Items)\n\nWhen each tab leads to an anchor, another page or a route, set `href` on every `<mds-tab-item>` and omit the `content` slot: the items render as links, the browser follows them (in a new tab on a modifier or middle click) and the strip keeps the selected item highlighted. The page content is driven by navigation, not by the managed-panels mechanism.\n\n```html\n<mds-tab>\n <mds-tab-item href=\"#sezione-1\" label=\"Introduzione\" selected></mds-tab-item>\n <mds-tab-item href=\"#sezione-2\" label=\"Requisiti\"></mds-tab-item>\n <mds-tab-item href=\"#sezione-3\" label=\"Conclusioni\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Client-Side Routing (href on Tab Items)\n\nIn a single-page app keep `href` on the items and register the router once with `NavigationService`, from `@maggioli-design-system/magma/services`: a plain click on an item is routed on the client and the selection still moves, with no listener per item. A modifier or middle click stays with the browser, which opens the link in a new tab while the strip stays as it is.\n\n```html\n<mds-tab id=\"sezioni\">\n <mds-tab-item href=\"/pratiche\" label=\"Pratiche\" selected></mds-tab-item>\n <mds-tab-item href=\"/documenti\" label=\"Documenti\"></mds-tab-item>\n <mds-tab-item href=\"/pagamenti\" label=\"Pagamenti\"></mds-tab-item>\n</mds-tab>\n\n<script type=\"module\">\n import { NavigationService } from '@maggioli-design-system/magma/services';\n\n NavigationService.setHandler((href) => router.navigate(href));\n</script>\n```\n\nWithout a registered router, cancel the click on the items and route by hand: the component honours `preventDefault()` and still moves the selection. Leave a modifier click alone.\n\n```html\n<script>\n document.querySelectorAll('#sezioni mds-tab-item').forEach((item) => {\n item.addEventListener('click', (event) => {\n if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;\n event.preventDefault();\n router.navigate(item.href);\n });\n });\n</script>\n```\n\n#### Disabled Tab Item\n\nMark an individual tab as unavailable with `disabled`. The parent's selection mechanism skips it; the tab is removed from the tab order automatically.\n\n```html\n<mds-tab>\n <mds-tab-item label=\"Attivo\" selected></mds-tab-item>\n <mds-tab-item label=\"Non disponibile\" disabled></mds-tab-item>\n <mds-tab-item label=\"Altro\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Contenuto disponibile.</mds-text></div>\n <div slot=\"content\"><mds-text>Contenuto non disponibile.</mds-text></div>\n <div slot=\"content\"><mds-text>Altro contenuto.</mds-text></div>\n</mds-tab>\n```\n\n#### Styling Customization\n\nStyle the component only through its public `--mds-tab-*` CSS custom properties: the background, margin and shadow of the tab strip and the columns of the vertical layout. The colours and shadows of the items and the timing of the transitions are not part of them. Set them on the host or a parent selector; use semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.scheda-primaria mds-tab {\n --mds-tab-tabs-background: rgb(var(--magma-accent-surface));\n --mds-tab-tabs-wrapper-shadow: 0 0 0 calc(var(--spacing) * 50) rgb(var(--magma-accent-border)) inset;\n}\n```\n\nWith `animation=\"fade\"` every item paints its own states (resting, hover and selected). With the slider (`animation=\"slide\"`) the items stay transparent over it, and the slider (`::part(slider)`) paints the selected one.\n",
29368
29902
  "3. Mistakes": "Common incorrect uses of `<mds-tab>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Size Individual Tab Items\n\nSetting `size` on a `<mds-tab-item>` directly is overridden by the parent at render time. Use the `size` prop on `<mds-tab>` to size all tabs uniformly.\n\n```html\n<!-- INCORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Elenco\" size=\"sm\" selected></mds-tab-item>\n <mds-tab-item label=\"Griglia\" size=\"sm\"></mds-tab-item>\n</mds-tab>\n\n<!-- CORRECT -->\n<mds-tab size=\"sm\">\n <mds-tab-item label=\"Elenco\" selected></mds-tab-item>\n <mds-tab-item label=\"Griglia\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Do Not Mix Tab Items and Content Panels Out of Order\n\nPanels in `slot=\"content\"` are wired to `<mds-tab-item>` elements by document order. A missing panel leaves its tab with no content, a wrong ordering shows the wrong panel when a tab is selected.\n\n```html\n<!-- INCORRECT: only two content panels for three tab items -->\n<mds-tab>\n <mds-tab-item label=\"A\" selected></mds-tab-item>\n <mds-tab-item label=\"B\"></mds-tab-item>\n <mds-tab-item label=\"C\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Pannello A.</mds-text></div>\n <div slot=\"content\"><mds-text>Pannello B.</mds-text></div>\n</mds-tab>\n\n<!-- CORRECT: one content panel per tab item, same order -->\n<mds-tab>\n <mds-tab-item label=\"A\" selected></mds-tab-item>\n <mds-tab-item label=\"B\"></mds-tab-item>\n <mds-tab-item label=\"C\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Pannello A.</mds-text></div>\n <div slot=\"content\"><mds-text>Pannello B.</mds-text></div>\n <div slot=\"content\"><mds-text>Pannello C.</mds-text></div>\n</mds-tab>\n```\n\n#### Do Not Mix Link Items and Panel Tabs in One Strip\n\nA strip is either a `tablist` of tabs, each controlling a panel, or a navigation of links (`href` on every item): a link inside a tablist is not a child the role allows, and assistive technology announces the strip wrong. Keep the link out of the strip, as an `<mds-button>` next to it.\n\n```html\n<!-- INCORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Dettagli\" selected></mds-tab-item>\n <mds-tab-item label=\"Allegati\"></mds-tab-item>\n <mds-tab-item label=\"Portale\" href=\"https://portale.example.com\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Dettagli.</mds-text></div>\n <div slot=\"content\"><mds-text>Allegati.</mds-text></div>\n <div slot=\"content\"></div>\n</mds-tab>\n\n<!-- CORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Dettagli\" selected></mds-tab-item>\n <mds-tab-item label=\"Allegati\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Dettagli.</mds-text></div>\n <div slot=\"content\"><mds-text>Allegati.</mds-text></div>\n</mds-tab>\n<mds-button label=\"Portale\" href=\"https://portale.example.com\" target=\"blank\" tone=\"text\"></mds-button>\n```\n\n#### Do Not Put Tab Items Outside `<mds-tab>`\n\n`<mds-tab-item>` communicates with its parent through internal Stencil events. Used outside `<mds-tab>` it renders as an inert button with no selection, panel, or keyboard management.\n\n```html\n<!-- INCORRECT -->\n<div class=\"my-tab-wrapper\">\n <mds-tab-item label=\"Scheda uno\" selected></mds-tab-item>\n <mds-tab-item label=\"Scheda due\"></mds-tab-item>\n</div>\n<div>...</div>\n\n<!-- CORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Scheda uno\" selected></mds-tab-item>\n <mds-tab-item label=\"Scheda due\"></mds-tab-item>\n <div slot=\"content\">...</div>\n <div slot=\"content\">...</div>\n</mds-tab>\n```\n\n#### Do Not Listen to the `mdsTabItemSelect` Event from Outside\n\n`mdsTabItemSelect` is the item-level event that `<mds-tab-item>` fires to its parent `<mds-tab>`: its `detail` carries the item element (`target`) and `value`, not the position of the tab. To react to the active tab of the group listen to `mdsTabChange` on `<mds-tab>`, whose `detail` has the tab index (`id`) and `value`.\n\n```html\n<!-- INCORRECT -->\n<mds-tab id=\"schede\">\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n <mds-tab-item label=\"Seconda\"></mds-tab-item>\n</mds-tab>\n\n<script>\n document.querySelector('#schede').addEventListener('mdsTabItemSelect', handler);\n</script>\n\n<!-- CORRECT -->\n<mds-tab id=\"schede\">\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n <mds-tab-item label=\"Seconda\"></mds-tab-item>\n</mds-tab>\n\n<script>\n document.querySelector('#schede').addEventListener('mdsTabChange', handler);\n</script>\n```\n\n#### Do Not Use `scrollbar=\"false\"` or `overflow=\"false\"` to Turn Off Boolean Props\n\nStencil reads `\"false\"` as `false` and, since both props are reflected, removes the attribute at the first render, so this happens to work; but the markup says the opposite of what it does, and on a prop that is not reflected the attribute stays in the DOM, where `[attr]` selectors still match it. Remove the attribute entirely to turn a prop off.\n\n```html\n<!-- INCORRECT -->\n<mds-tab scrollbar=\"false\" overflow=\"false\">\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n</mds-tab>\n\n<!-- CORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n</mds-tab>\n```\n\n#### Do Not Place Raw HTML Instead of `<mds-tab-item>` in the Default Slot\n\nThe default slot expects `<mds-tab-item>` elements only. Placing a raw `<button>` or `<a>` there bypasses the ARIA `tablist` structure, selection management, and keyboard handling that `<mds-tab>` provides.\n\n```html\n<!-- INCORRECT -->\n<mds-tab>\n <button class=\"tab\">Documenti</button>\n <button class=\"tab\">Messaggi</button>\n <div slot=\"content\">...</div>\n <div slot=\"content\">...</div>\n</mds-tab>\n\n<!-- CORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Documenti\" selected></mds-tab-item>\n <mds-tab-item label=\"Messaggi\"></mds-tab-item>\n <div slot=\"content\">...</div>\n <div slot=\"content\">...</div>\n</mds-tab>\n```\n\n#### Do Not Customize via Undocumented Shadow Parts or Internal Selectors\n\nThe supported customization surface is the public `--mds-tab-*` CSS custom properties and the documented shadow parts (`tabs`, `contents`, `slider`). Targeting other internals via `>>>`, `/deep/`, or undocumented class names couples your code to the shadow DOM implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-tab >>> .tabs-wrapper {\n background: red;\n}\nmds-tab::part(tabs-wrapper) {\n padding: 0;\n}\n\n/* CORRECT */\nmds-tab {\n --mds-tab-tabs-background: rgb(var(--magma-accent-surface));\n}\nmds-tab::part(tabs) {\n outline: 2px solid rgb(var(--magma-accent-border));\n}\n```\n"
29369
29903
  },
@@ -29817,6 +30351,7 @@
29817
30351
  ],
29818
30352
  "states": [],
29819
30353
  "dependents": [
30354
+ "mds-input-date-range",
29820
30355
  "mds-input-upload",
29821
30356
  "mds-pref-animation",
29822
30357
  "mds-pref-consumption",
@@ -29827,6 +30362,9 @@
29827
30362
  ],
29828
30363
  "dependencies": [],
29829
30364
  "dependencyGraph": {
30365
+ "mds-input-date-range": [
30366
+ "mds-tab"
30367
+ ],
29830
30368
  "mds-input-upload": [
29831
30369
  "mds-tab"
29832
30370
  ],
@@ -30667,6 +31205,7 @@
30667
31205
  ],
30668
31206
  "states": [],
30669
31207
  "dependents": [
31208
+ "mds-input-date-range",
30670
31209
  "mds-input-upload",
30671
31210
  "mds-pref-animation",
30672
31211
  "mds-pref-consumption",
@@ -30683,10 +31222,13 @@
30683
31222
  "mds-button"
30684
31223
  ],
30685
31224
  "mds-button": [
30686
- "mds-spinner",
30687
31225
  "mds-icon",
31226
+ "mds-spinner",
30688
31227
  "mds-text"
30689
31228
  ],
31229
+ "mds-input-date-range": [
31230
+ "mds-tab-item"
31231
+ ],
30690
31232
  "mds-input-upload": [
30691
31233
  "mds-tab-item"
30692
31234
  ],
@@ -30748,8 +31290,8 @@
30748
31290
  }
30749
31291
  ],
30750
31292
  "usage": {
30751
- "1. Description": "The `<mds-table>` web component is the root container of the Magma Design System tabular data system. It wraps a native `<table>` and orchestrates a family of compound children (`mds-table-header`, `mds-table-body`, `mds-table-footer`, `mds-table-row`, `mds-table-cell`), propagating interaction, selection, and overflow state down to them.\n\n#### Semantic Behavior\n\n- **Compound parent**: The default slot must hold `mds-table-header` / `mds-table-body` / `mds-table-footer`; `<mds-table>` pushes its own `interactive` and `selectable` state onto every `mds-table-row` and the header/body. It is not used standalone.\n- **Selection model**: When `selectable` is set, rows expose a checkbox; the component aggregates the selected rows, mirrors the count to the header's tristate control, and flags that a selection exists so it is visible to CSS and consumers.\n- **Selection event**: Emits `mdsTableSelectionChange` (bubbles, composed) carrying `{ rows }`, an array of `{ index, value }` for every selected row. It follows every change of a row's `selected`, from its checkbox or from code, and `selectAll(select?)`; changes made together are announced once. Both are no-ops unless `selectable` is true.\n- **Live children**: Rows added or removed at runtime are re-wired with the table's interactive and selectable state, so dynamically added rows behave consistently.\n- **Action overflow**: When rows carry a `[slot=\"action\"]`, rows flip into an overlaid-action mode once content exceeds the visible width. Rows and actions added after the first load are followed too: the header gains its Actions column and the new rows the overlay.\n- **Localization**: Resolves its display language from the page (`<html lang>`: `el`/`en`/`es`/`it`, otherwise `en`) for the batch-actions label.\n\n#### Properties & Visual Configurations\n\n- **`interactive`** highlights rows on mouseover; choose it for tables whose rows are clickable or navigable, not for purely static read-only data.\n- **`selectable`** turns on per-row checkbox selection and the aggregated header/batch-actions machinery; without it the selection methods and the `batch-action` slot are inert.\n- **`selection`** is a read-back flag that becomes true while at least one row is selected - it is managed internally, not something callers normally set.\n- **`sorting`** says who orders the rows when a sortable `mds-table-header-cell` changes direction. `internal` (default) moves the rows in the DOM; `external` leaves them where they are, so the application listens to `mdsTableHeaderCellSort` and renders the rows in the order asked. Choose `external` whenever the table shows one page of a larger set (with `mds-paginator`) or the order comes from a back end: sorting the DOM would only sort the page on screen.\n\n#### Other behavioral props\n\n- **`batch-action` slot** holds `mds-button` element/s; its bar renders only when `selectable` is on and at least one batch action is slotted, surfacing a live count badge of the current selection.\n",
30752
- "2. Examples": "Correct and idiomatic ways to use the `<mds-table>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Read-Only Table\n\nThe minimal structure: `mds-table-header` with one `mds-table-header-cell` per column, `mds-table-body` with `mds-table-row` children each containing `mds-table-cell` elements. All four subparts are required direct children - do not replace them with raw `<thead>`, `<tr>`, or `<td>` elements.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data iscrizione\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">mario.rossi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">12 ottobre 1985</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Luigi Verdi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">luigi.verdi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">3 marzo 1993</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Layout: Fill the Container and Let the Table Scroll\n\n`<mds-table>` scrolls on its own: its rows sit in an inner wrapper with `overflow: auto`, so when the columns are wider than the table, the table scrolls horizontally inside its own border, and the row actions (`slot=\"action\"`) stay pinned to the visible right edge. It needs no `overflow-x-auto` wrapper of yours, but it needs two things from the page:\n\n- **All the width its container offers**: `w-full` on `<mds-table>`. When that container is a flex or grid item (a `main` next to a sidebar, a `1fr` column), also give the item `min-w-0`: a flex or grid item never shrinks below its content by default, so without it the item grows to the full width of the table and the whole page scrolls instead of the table.\n- **Cells on one line**: `text-wrap: nowrap` on the cells (`[&_mds-table-cell]:text-nowrap` on the table). Wrapping cells squeeze the columns into tall rows and the table never scrolls. `mds-text` with `typography` `paragraph`, `detail` or `caption` sets its own `text-wrap: pretty`, which wins over what it inherits from the cell, so target it too (`[&_mds-text]:text-nowrap`). A long free-text column can keep wrapping if it reads better.\n\n```html\n<div class=\"flex\">\n <aside class=\"w-6400 shrink-0\">...</aside>\n <main class=\"min-w-0 flex-1\">\n <mds-table class=\"w-full [&_mds-table-cell]:text-nowrap [&_mds-text]:text-nowrap\">\n <mds-table-header>\n <mds-table-header-cell label=\"Protocollo\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Oggetto\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ufficio\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">2026/0412</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Contratto di fornitura servizi cloud 2026-2028</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Ufficio acquisti e gare</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">12 marzo 2026</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n </mds-table>\n </main>\n</div>\n```\n\nTo scroll vertically as well, bound the table's height: in a fixed-height panel, make the panel a flex column and give the table `flex-1 min-h-0` (or put `h-full` or a `max-h-*` on the table). The header row scrolls with the body, it is not sticky.\n\n```html\n<section class=\"flex h-9600 flex-col\">\n <mds-table class=\"min-h-0 flex-1 [&_mds-table-cell]:text-nowrap [&_mds-text]:text-nowrap\">\n ...\n </mds-table>\n</section>\n```\n\nWithout Tailwind, the same rules in CSS:\n\n```css\n.content {\n min-width: 0;\n}\n\n.content mds-table {\n width: 100%;\n}\n\n.content mds-table-cell,\n.content mds-table-cell mds-text {\n text-wrap: nowrap;\n}\n```\n\n#### Table with Footer\n\nAdd `mds-table-footer` after `mds-table-body` to show totals or summaries. Each cell inside the footer is an `mds-table-cell` - the same component used in body rows.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Voce\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Importo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Servizio A</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">120,00 EUR</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Servizio B</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">80,00 EUR</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-table-footer>\n <mds-table-cell><mds-text typography=\"action\">Totale</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"action\">200,00 EUR</mds-text></mds-table-cell>\n </mds-table-footer>\n</mds-table>\n```\n\n#### Interactive Rows\n\nSet `interactive` when rows are clickable or navigable. The prop propagates to every `mds-table-row` and highlights the hovered row. Do not reach into rows directly to set `interactive` - set it once on the parent.\n\n```html\n<mds-table interactive>\n <mds-table-header>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ruolo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Anna Bianchi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Amministratore</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Carlo Neri</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Operatore</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Row-Level Action Buttons\n\nSlot `mds-button` elements with `slot=\"action\"` directly inside `mds-table-row` (not inside `mds-table-cell`). The table detects the presence of action buttons and switches to overlay-action mode automatically when content overflows the visible width.\n\n```html\n<mds-table interactive>\n <mds-table-header>\n <mds-table-header-cell label=\"Documento\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Contratto 2024.pdf</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Approvato</mds-text></mds-table-cell>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/download\"\n title=\"Scarica documento\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/delete\"\n title=\"Elimina documento\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Row Selection and Selection Event\n\nSet `selectable` to add a checkbox to each row. Listen for `mdsTableSelectionChange` to receive the array of selected rows - each entry carries the row `index` and the optional `value` set on `mds-table-row`. Assign `value` to each row to distinguish selections in the event payload.\n\n```html\n<mds-table selectable id=\"tabella-utenti\">\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Reparto\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"usr-001\">\n <mds-table-cell><mds-text typography=\"detail\">Giulia Russo</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Contabilita</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"usr-002\">\n <mds-table-cell><mds-text typography=\"detail\">Marco Ferrari</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">IT</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n document.getElementById('tabella-utenti').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n // e.detail.rows => [{ index: 0, value: 'usr-001' }, ...]\n });\n</script>\n```\n\n#### Programmatic Select All\n\nCall the `selectAll()` method to select all rows at once; pass `false` to deselect. This is a no-op unless `selectable` is set.\n\n```html\n<mds-button id=\"btn-seleziona-tutti\" label=\"Seleziona tutti\" variant=\"primary\" tone=\"outline\"></mds-button>\n<mds-button id=\"btn-deseleziona\" label=\"Deseleziona tutti\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-table selectable id=\"tabella-doc\">\n <mds-table-header>\n <mds-table-header-cell label=\"Titolo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"doc-1\">\n <mds-table-cell><mds-text typography=\"detail\">Verbale assemblea</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"doc-2\">\n <mds-table-cell><mds-text typography=\"detail\">Bilancio 2024</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n const table = document.getElementById('tabella-doc');\n document.getElementById('btn-seleziona-tutti').addEventListener('click', () => table.selectAll());\n document.getElementById('btn-deseleziona').addEventListener('click', () => table.selectAll(false));\n</script>\n```\n\n#### Batch Actions Bar\n\nSlot `mds-button` elements with `slot=\"batch-action\"` as direct children of `mds-table` alongside the body. The bar renders only when `selectable` is set and at least one batch-action button is present, a button added after load included; it shows a live count badge of the current selection and appears once a row is checked.\n\n```html\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Pratica\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"prat-001\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica n. 1234</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">In lavorazione</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"prat-002\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica n. 5678</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Chiusa</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-button\n slot=\"batch-action\"\n icon=\"mi/outline/send\"\n label=\"Invia selezionati\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n <mds-button\n slot=\"batch-action\"\n icon=\"mi/outline/delete\"\n label=\"Elimina selezionati\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n</mds-table>\n```\n\n#### Sorting by the Back End, with Pages\n\nWhen the table shows one page of a larger set, set `sorting=\"external\"`: a click on a sortable header emits `mdsTableHeaderCellSort` with the column (`index`, and `sortKey` when the cell has `sort-key`) and the `direction`, and moves no row. The application asks the back end for the first page in that order and renders it; the header shows the direction (icon and `aria-sort`). A `direction` set by the application, for example restored from the address, is shown the same way.\n\n```html\n<mds-table id=\"practices\" sorting=\"external\">\n <mds-table-header>\n <mds-table-header-cell label=\"Numero\" sortable sort-key=\"number\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ricevuta il\" sortable sort-key=\"received\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Oggetto\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <!-- the rows of the current page, rendered by the application -->\n </mds-table-body>\n</mds-table>\n<mds-paginator id=\"pages\" pages=\"12\"></mds-paginator>\n```\n\n```js\nconst table = document.querySelector('#practices');\nconst pages = document.querySelector('#pages');\n\ntable.addEventListener('mdsTableHeaderCellSort', async (event) => {\n const { sortKey, direction } = event.detail;\n // direction \"none\" asks for the order of the back end\n await loadPage({ page: 1, sort: direction === 'none' ? undefined : { sortKey, direction } });\n pages.currentPage = 1;\n});\n```\n\n#### Styling Customization\n\nCustomize the table appearance only through its public `--mds-table-*` CSS custom properties: the background, the text colour and the cell padding. Set them on the host element or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and themes keep working.\n\n```css\n.tabella-contratti mds-table {\n --mds-table-background: rgb(var(--magma-surface-raised));\n --mds-table-cell-padding: calc(var(--spacing) * 500);\n --mds-table-color: rgb(var(--magma-text-default));\n}\n```\n\nThe frame of the table and the lines inside it - between the rows, under the header, above the footer and at the edge of the batch actions panel - take the `--magma-border-muted` role, so frame and grid read as one and follow the theme and the colour mode.\n",
31293
+ "1. Description": "The `<mds-table>` web component is the root container of the Magma Design System tabular data system. It wraps a native `<table>` and orchestrates a family of compound children (`mds-table-header`, `mds-table-body`, `mds-table-footer`, `mds-table-row`, `mds-table-cell`), propagating interaction, selection, and overflow state down to them.\n\n#### Semantic Behavior\n\n- **Compound parent**: The default slot must hold `mds-table-header` / `mds-table-body` / `mds-table-footer`; `<mds-table>` pushes its own `interactive` and `selectable` state onto every `mds-table-row` and the header/body. It is not used standalone.\n- **Selection model**: When `selectable` is set, rows expose a checkbox; the component aggregates the selected rows, mirrors the count to the header's tristate control, and flags that a selection exists so it is visible to CSS and consumers.\n- **Selection event**: Emits `mdsTableSelectionChange` (bubbles, composed) carrying `{ rows }`, an array of `{ index, value }` for every selected row. It follows every change of a row's `selected`, from its checkbox or from code, and `selectAll(select?)`; changes made together are announced once. Rows that arrive already `selected` (in the markup on load, or rendered later) are counted but not announced, as a native control fires no `change` for its initial value. Both are no-ops unless `selectable` is true.\n- **Live children**: Rows added or removed at runtime are re-wired with the table's interactive and selectable state and counted in the selection, so dynamically added rows behave consistently.\n- **Action overflow**: When rows carry a `[slot=\"action\"]`, rows flip into an overlaid-action mode once content exceeds the visible width. Rows and actions added after the first load are followed too: the header gains its Actions column and the new rows the overlay.\n- **Localization**: Resolves its display language from the page (`<html lang>`: `el`/`en`/`es`/`it`, otherwise `en`) for the batch-actions label.\n\n#### Properties & Visual Configurations\n\n- **`interactive`** highlights rows on mouseover; choose it for tables whose rows are clickable or navigable, not for purely static read-only data.\n- **`selectable`** turns on per-row checkbox selection and the aggregated header/batch-actions machinery; without it the selection methods and the `batch-action` slot are inert.\n- **`selection`** is a read-back flag that becomes true while at least one row is selected - it is managed internally, not something callers normally set.\n- **`sorting`** says who orders the rows when a sortable `mds-table-header-cell` changes direction. `internal` (default) moves the rows in the DOM; `external` leaves them where they are, so the application listens to `mdsTableHeaderCellSort` and renders the rows in the order asked. Choose `external` whenever the table shows one page of a larger set (with `mds-paginator`) or the order comes from a back end: sorting the DOM would only sort the page on screen.\n\n#### Other behavioral props\n\n- **`batch-action` slot** holds `mds-button` element/s; its bar renders only when `selectable` is on and at least one batch action is slotted, surfacing a live count badge of the current selection.\n",
31294
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-table>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Read-Only Table\n\nThe minimal structure: `mds-table-header` with one `mds-table-header-cell` per column, `mds-table-body` with `mds-table-row` children each containing `mds-table-cell` elements. All four subparts are required direct children - do not replace them with raw `<thead>`, `<tr>`, or `<td>` elements.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data iscrizione\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">mario.rossi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">12 ottobre 1985</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Luigi Verdi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">luigi.verdi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">3 marzo 1993</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Layout: Fill the Container and Let the Table Scroll\n\n`<mds-table>` scrolls on its own: its rows sit in an inner wrapper with `overflow: auto`, so when the columns are wider than the table, the table scrolls horizontally inside its own border, and the row actions (`slot=\"action\"`) stay pinned to the visible right edge. It needs no `overflow-x-auto` wrapper of yours, but it needs two things from the page:\n\n- **All the width its container offers**: `w-full` on `<mds-table>`. When that container is a flex or grid item (a `main` next to a sidebar, a `1fr` column), also give the item `min-w-0`: a flex or grid item never shrinks below its content by default, so without it the item grows to the full width of the table and the whole page scrolls instead of the table.\n- **Cells on one line**: `text-wrap: nowrap` on the cells (`[&_mds-table-cell]:text-nowrap` on the table). Wrapping cells squeeze the columns into tall rows and the table never scrolls. `mds-text` with `typography` `paragraph`, `detail` or `caption` sets its own `text-wrap: pretty`, which wins over what it inherits from the cell, so target it too (`[&_mds-text]:text-nowrap`). A long free-text column can keep wrapping if it reads better.\n\n```html\n<div class=\"flex\">\n <aside class=\"w-6400 shrink-0\">...</aside>\n <main class=\"min-w-0 flex-1\">\n <mds-table class=\"w-full [&_mds-table-cell]:text-nowrap [&_mds-text]:text-nowrap\">\n <mds-table-header>\n <mds-table-header-cell label=\"Protocollo\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Oggetto\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ufficio\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">2026/0412</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Contratto di fornitura servizi cloud 2026-2028</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Ufficio acquisti e gare</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">12 marzo 2026</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n </mds-table>\n </main>\n</div>\n```\n\nTo scroll vertically as well, bound the table's height: in a fixed-height panel, make the panel a flex column and give the table `flex-1 min-h-0` (or put `h-full` or a `max-h-*` on the table). The header row scrolls with the body, it is not sticky.\n\n```html\n<section class=\"flex h-9600 flex-col\">\n <mds-table class=\"min-h-0 flex-1 [&_mds-table-cell]:text-nowrap [&_mds-text]:text-nowrap\">\n ...\n </mds-table>\n</section>\n```\n\nWithout Tailwind, the same rules in CSS:\n\n```css\n.content {\n min-width: 0;\n}\n\n.content mds-table {\n width: 100%;\n}\n\n.content mds-table-cell,\n.content mds-table-cell mds-text {\n text-wrap: nowrap;\n}\n```\n\n#### Table with Footer\n\nAdd `mds-table-footer` after `mds-table-body` to show totals or summaries. Each cell inside the footer is an `mds-table-cell` - the same component used in body rows.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Voce\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Importo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Servizio A</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">120,00 EUR</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Servizio B</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">80,00 EUR</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-table-footer>\n <mds-table-cell><mds-text typography=\"action\">Totale</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"action\">200,00 EUR</mds-text></mds-table-cell>\n </mds-table-footer>\n</mds-table>\n```\n\n#### Interactive Rows\n\nSet `interactive` when rows are clickable or navigable. The prop propagates to every `mds-table-row` and highlights the hovered row. Do not reach into rows directly to set `interactive` - set it once on the parent.\n\n```html\n<mds-table interactive>\n <mds-table-header>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ruolo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Anna Bianchi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Amministratore</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Carlo Neri</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Operatore</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Row-Level Action Buttons\n\nSlot `mds-button` elements with `slot=\"action\"` directly inside `mds-table-row` (not inside `mds-table-cell`). The table detects the presence of action buttons and switches to overlay-action mode automatically when content overflows the visible width.\n\n```html\n<mds-table interactive>\n <mds-table-header>\n <mds-table-header-cell label=\"Documento\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Contratto 2024.pdf</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Approvato</mds-text></mds-table-cell>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/download\"\n title=\"Scarica documento\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/delete\"\n title=\"Elimina documento\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Row Selection and Selection Event\n\nSet `selectable` to add a checkbox to each row. Listen for `mdsTableSelectionChange` to receive the array of selected rows - each entry carries the row `index` and the optional `value` set on `mds-table-row`. Assign `value` to each row to distinguish selections in the event payload.\n\n```html\n<mds-table selectable id=\"tabella-utenti\">\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Reparto\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"usr-001\">\n <mds-table-cell><mds-text typography=\"detail\">Giulia Russo</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Contabilita</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"usr-002\">\n <mds-table-cell><mds-text typography=\"detail\">Marco Ferrari</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">IT</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n document.getElementById('tabella-utenti').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n // e.detail.rows => [{ index: 0, value: 'usr-001' }, ...]\n });\n</script>\n```\n\n#### Rows Selected on Load\n\nWrite `selected` on the rows that start selected, such as a selection the page restores. The table counts them when it loads, as after a click: the header box turns indeterminate (checked when every row is selected) and the bar of the batch actions shows how many. Rows rendered later already `selected` are counted the same way. `mdsTableSelectionChange` is not emitted for them, as a native control fires no `change` for its initial value: the application wrote them, so it already knows them.\n\n```html\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Pratica\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"2026/0097\" selected>\n <mds-table-cell><mds-text typography=\"detail\">Iscrizione anagrafica</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"2026/0094\">\n <mds-table-cell><mds-text typography=\"detail\">Certificato di residenza</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-button slot=\"batch-action\" variant=\"primary\" tone=\"outline\" size=\"sm\">Archivia</mds-button>\n</mds-table>\n```\n\n#### Programmatic Select All\n\nCall the `selectAll()` method to select all rows at once; pass `false` to deselect. This is a no-op unless `selectable` is set.\n\n```html\n<mds-button id=\"btn-seleziona-tutti\" label=\"Seleziona tutti\" variant=\"primary\" tone=\"outline\"></mds-button>\n<mds-button id=\"btn-deseleziona\" label=\"Deseleziona tutti\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-table selectable id=\"tabella-doc\">\n <mds-table-header>\n <mds-table-header-cell label=\"Titolo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"doc-1\">\n <mds-table-cell><mds-text typography=\"detail\">Verbale assemblea</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"doc-2\">\n <mds-table-cell><mds-text typography=\"detail\">Bilancio 2024</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n const table = document.getElementById('tabella-doc');\n document.getElementById('btn-seleziona-tutti').addEventListener('click', () => table.selectAll());\n document.getElementById('btn-deseleziona').addEventListener('click', () => table.selectAll(false));\n</script>\n```\n\n#### Batch Actions Bar\n\nSlot `mds-button` elements with `slot=\"batch-action\"` as direct children of `mds-table` alongside the body. The bar renders only when `selectable` is set and at least one batch-action button is present, a button added after load included; it shows a live count badge of the current selection and appears once a row is checked.\n\n```html\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Pratica\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"prat-001\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica n. 1234</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">In lavorazione</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"prat-002\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica n. 5678</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Chiusa</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-button\n slot=\"batch-action\"\n icon=\"mi/outline/send\"\n label=\"Invia selezionati\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n <mds-button\n slot=\"batch-action\"\n icon=\"mi/outline/delete\"\n label=\"Elimina selezionati\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n</mds-table>\n```\n\n#### Sorting by the Back End, with Pages\n\nWhen the table shows one page of a larger set, set `sorting=\"external\"`: a click on a sortable header emits `mdsTableHeaderCellSort` with the column (`index`, and `sortKey` when the cell has `sort-key`) and the `direction`, and moves no row. The application asks the back end for the first page in that order and renders it; the header shows the direction (icon and `aria-sort`). A `direction` set by the application, for example restored from the address, is shown the same way.\n\n```html\n<mds-table id=\"practices\" sorting=\"external\">\n <mds-table-header>\n <mds-table-header-cell label=\"Numero\" sortable sort-key=\"number\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ricevuta il\" sortable sort-key=\"received\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Oggetto\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <!-- the rows of the current page, rendered by the application -->\n </mds-table-body>\n</mds-table>\n<mds-paginator id=\"pages\" pages=\"12\"></mds-paginator>\n```\n\n```js\nconst table = document.querySelector('#practices');\nconst pages = document.querySelector('#pages');\n\ntable.addEventListener('mdsTableHeaderCellSort', async (event) => {\n const { sortKey, direction } = event.detail;\n // direction \"none\" asks for the order of the back end\n await loadPage({ page: 1, sort: direction === 'none' ? undefined : { sortKey, direction } });\n pages.currentPage = 1;\n});\n```\n\n#### Styling Customization\n\nCustomize the table appearance only through its public `--mds-table-*` CSS custom properties: the background, the text colour and the cell padding. Set them on the host element or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and themes keep working.\n\n```css\n.tabella-contratti mds-table {\n --mds-table-background: rgb(var(--magma-surface-raised));\n --mds-table-cell-padding: calc(var(--spacing) * 500);\n --mds-table-color: rgb(var(--magma-text-default));\n}\n```\n\nThe frame of the table and the lines inside it - between the rows, under the header, above the footer and at the edge of the batch actions panel - take the `--magma-border-muted` role, so frame and grid read as one and follow the theme and the colour mode.\n",
30753
31295
  "3. Mistakes": "Common incorrect uses of `<mds-table>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Replace Compound Subparts with Raw HTML Elements\n\n`<mds-table>` orchestrates its children via internal Stencil mechanisms. Substituting any subpart (`mds-table-header`, `mds-table-body`, `mds-table-row`, `mds-table-cell`) with a raw `<thead>`, `<tbody>`, `<tr>`, or `<td>` breaks propagation of `interactive`, `selectable`, and overflow state.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <thead>\n <tr><th>Nome</th><th>Email</th></tr>\n </thead>\n <tbody>\n <tr><td>Mario Rossi</td><td>mario.rossi@example.com</td></tr>\n </tbody>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">mario.rossi@example.com</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Do Not Slot Batch-Action Buttons Inside the Body\n\nThe `slot=\"batch-action\"` must be a direct child of `<mds-table>`, not nested inside `mds-table-body` or any row. The component looks for `:scope > [slot=\"batch-action\"]` on load and whenever its children change, and the bar will not appear if the slot is misplaced.\n\n```html\n<!-- INCORRECT -->\n<mds-table selectable>\n <mds-table-body>\n <mds-table-row>...</mds-table-row>\n <mds-button slot=\"batch-action\" label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table selectable>\n <mds-table-header>...</mds-table-header>\n <mds-table-body>\n <mds-table-row>...</mds-table-row>\n </mds-table-body>\n <mds-button slot=\"batch-action\" label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-table>\n```\n\n#### Do Not Slot Row Action Buttons Inside `mds-table-cell`\n\nPer-row action buttons use `slot=\"action\"` on a direct child of `mds-table-row`, not wrapped inside an `mds-table-cell`. Placing them in a cell hides them (`mds-table-cell` has no `action` slot, so the button is not rendered) and breaks the overflow-detection logic that switches rows into overlay-action mode.\n\n```html\n<!-- INCORRECT -->\n<mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Contratto.pdf</mds-text></mds-table-cell>\n <mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" title=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-table-cell>\n</mds-table-row>\n\n<!-- CORRECT -->\n<mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Contratto.pdf</mds-text></mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" title=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-table-row>\n```\n\n#### Do Not Enable Batch Actions Without `selectable`\n\nThe batch-action bar only renders when `selectable` is set. Slotting batch-action buttons on a non-selectable table silently produces no bar and no selection count, causing the buttons to never appear.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header>...</mds-table-header>\n <mds-table-body>...</mds-table-body>\n <mds-button slot=\"batch-action\" label=\"Esporta\" variant=\"primary\"></mds-button>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table selectable>\n <mds-table-header>...</mds-table-header>\n <mds-table-body>...</mds-table-body>\n <mds-button slot=\"batch-action\" label=\"Esporta\" variant=\"primary\"></mds-button>\n</mds-table>\n```\n\n#### Do Not Set `interactive` on Individual Rows\n\n`interactive` is a table-level prop that propagates automatically to every `mds-table-row`. Setting it directly on individual rows bypasses the table's state management and leads to inconsistent behavior when rows are added or removed at runtime.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-body>\n <mds-table-row interactive>...</mds-table-row>\n <mds-table-row>...</mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table interactive>\n <mds-table-body>\n <mds-table-row>...</mds-table-row>\n <mds-table-row>...</mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Do Not Listen for Native `change` Events to Track Selection\n\nSelection state is communicated via the `mdsTableSelectionChange` custom event. Native `change` events from the internal checkboxes do not bubble out of the shadow DOM reliably; always use the documented Magma event.\n\n```html\n<!-- INCORRECT -->\n<mds-table selectable id=\"tbl\">...</mds-table>\n<script>\n document.getElementById('tbl').addEventListener('change', (e) => {\n // unreliable - native events do not bubble from shadow DOM\n });\n</script>\n\n<!-- CORRECT -->\n<mds-table selectable id=\"tbl\">...</mds-table>\n<script>\n document.getElementById('tbl').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n });\n</script>\n```\n\n#### Do Not Set `selection` Manually\n\n`selection` is a reflected read-back attribute managed internally by the table. It becomes `true` when at least one row is selected and is intended for CSS attribute selectors or conditional logic in the host app. Setting it from outside does not change which rows are selected and will be overwritten on the next selection update. The table emits `mdsTableSelectionChange` before it updates `selection`, so inside that listener read `e.detail.rows`, not the attribute.\n\n```html\n<!-- INCORRECT -->\n<mds-table selectable selection>\n ...\n</mds-table>\n\n<!-- CORRECT - read it back, do not set it -->\n<mds-table selectable id=\"tbl\">\n ...\n</mds-table>\n<script>\n document.getElementById('tbl').addEventListener('mdsTableSelectionChange', (e) => {\n const hasSelection = e.detail.rows.length > 0;\n document.getElementById('panel-azioni').hidden = !hasSelection;\n });\n</script>\n```\n"
30754
31296
  },
30755
31297
  "props": [
@@ -30951,15 +31493,15 @@
30951
31493
  "location": "global",
30952
31494
  "id": "global::Promise"
30953
31495
  },
30954
- "HTMLMdsTableRowElement": {
30955
- "location": "global",
30956
- "id": "global::HTMLMdsTableRowElement"
30957
- },
30958
31496
  "MdsTableRowSelection": {
30959
31497
  "location": "import",
30960
31498
  "path": "./meta/type",
30961
31499
  "id": "src/components/mds-table/meta/type.ts::MdsTableRowSelection",
30962
31500
  "referenceLocation": "MdsTableRowSelection"
31501
+ },
31502
+ "HTMLMdsTableRowElement": {
31503
+ "location": "global",
31504
+ "id": "global::HTMLMdsTableRowElement"
30963
31505
  }
30964
31506
  },
30965
31507
  "return": "Promise<void>"
@@ -30989,7 +31531,7 @@
30989
31531
  },
30990
31532
  "cancelable": true,
30991
31533
  "composed": true,
30992
- "docs": "Emits when the selection of a `selectable` table changes, with the index and the value of each\nselected row",
31534
+ "docs": "Emits when the selection of a `selectable` table changes, with the index and the value of each\nselected row. It announces changes only: not the rows that arrive already `selected` (in the\nmarkup on load, or rendered later), which the table counts all the same, as a native control\nfires no `change` for its initial value",
30993
31535
  "docsTags": []
30994
31536
  }
30995
31537
  ],
@@ -31419,9 +31961,9 @@
31419
31961
  }
31420
31962
  ],
31421
31963
  "usage": {
31422
- "1. Description": "The `<mds-table-header>` web component is the header region of a Magma table, used exclusively as a direct slot child of its parent [`<mds-table>`](../mds-table/AGENTS.md). It plays the role of an HTML `<thead>`/header row, hosting the column-header cells and, when selection is enabled, the master \"select all\" control.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be slotted directly inside `<mds-table>` alongside `mds-table-body` (and optionally `mds-table-footer`); it is not used standalone. It is itself the header row: its own default slot accepts `mds-table-header-cell` element(s), one per column.\n- **Parent-driven selection state**: When `selectable` is true the header renders a master checkbox that the parent keeps in sync - `indeterminate` for partial selection and `checked` when all rows are selected.\n- **Selection reported upward**: Toggling the master checkbox selects or deselects every row, after which the table re-emits its own `mdsTableSelectionChange` event.\n- **Automatic actions column**: When any row exposes a `[slot=\"action\"]`, the header appends an extra header cell (exposed as the `actions` shadow part) labelled with the localized \"actions\" string.\n- **Localized labels**: The select-all/select-none switch title and the actions label are localized (el/en/es/it).\n\n#### Properties & Visual Configurations\n\nThis child is configured almost entirely by its parent rather than by author-set attributes.\n\n- **`selectable`**: Toggles rendering of the leading master-checkbox column. It is not normally set by hand - `<mds-table>` propagates its own `selectable` prop down to the header, so enabling selection on the table is what surfaces this control here.\n\nBeyond `selectable`, content is provided through the default slot (`mds-table-header-cell` elements); there are no shared `variant`/`tone` ladders on this component.\n",
31964
+ "1. Description": "The `<mds-table-header>` web component is the header region of a Magma table, used exclusively as a direct slot child of its parent [`<mds-table>`](../mds-table/AGENTS.md). It plays the role of an HTML `<thead>`/header row, hosting the column-header cells and, when selection is enabled, the master \"select all\" control.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be slotted directly inside `<mds-table>` alongside `mds-table-body` (and optionally `mds-table-footer`); it is not used standalone. It is itself the header row: its own default slot accepts `mds-table-header-cell` element(s), one per column.\n- **Parent-driven selection state**: When `selectable` is true the header renders a master checkbox that the parent keeps in sync - `indeterminate` for partial selection and `checked` when all rows are selected, rows selected in the markup on load included.\n- **Selection reported upward**: Toggling the master checkbox selects or deselects every row, after which the table re-emits its own `mdsTableSelectionChange` event.\n- **Automatic actions column**: When any row exposes a `[slot=\"action\"]`, the header appends an extra header cell (exposed as the `actions` shadow part) labelled with the localized \"actions\" string.\n- **Localized labels**: The select-all/select-none switch title and the actions label are localized (el/en/es/it). The title says what a click on the switch does: select every row, or deselect them once every row is selected, however they got selected.\n\n#### Properties & Visual Configurations\n\nThis child is configured almost entirely by its parent rather than by author-set attributes.\n\n- **`selectable`**: Toggles rendering of the leading master-checkbox column. It is not normally set by hand - `<mds-table>` propagates its own `selectable` prop down to the header, so enabling selection on the table is what surfaces this control here.\n\nBeyond `selectable`, content is provided through the default slot (`mds-table-header-cell` elements); there are no shared `variant`/`tone` ladders on this component.\n",
31423
31965
  "2. Examples": "Correct and idiomatic ways to use the `<mds-table-header>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Column Headers\n\nPlace `<mds-table-header>` as a direct child of `<mds-table>` and fill its default slot with one `<mds-table-header-cell>` per column. Use the `label` prop on each cell - it is the only text source the cell needs.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data registrazione\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <!-- mds-table-row elements -->\n </mds-table-body>\n</mds-table>\n```\n\n#### Sortable Columns\n\nAdd the `sortable` attribute on the `<mds-table-header-cell>` elements whose column should be sortable. The cell cycles through `none`, `ascending`, and `descending` on each click and re-orders the corresponding body rows automatically.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell sortable label=\"Cognome\"></mds-table-header-cell>\n <mds-table-header-cell sortable label=\"Data\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Note\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <!-- mds-table-row elements -->\n </mds-table-body>\n</mds-table>\n```\n\n#### Selectable Table with Master Checkbox\n\nEnable row selection by adding `selectable` on `<mds-table>`. The table propagates the prop down to `<mds-table-header>`, which automatically renders the master \"select all\" checkbox as the first column. Never set `selectable` directly on `<mds-table-header>` - drive it from the table.\n\n```html\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ruolo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"1\">\n <mds-table-cell>Mario Rossi</mds-table-cell>\n <mds-table-cell>Amministratore</mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"2\">\n <mds-table-cell>Giulia Bianchi</mds-table-cell>\n <mds-table-cell>Editor</mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Reacting to Selection Changes\n\nListen for `mdsTableSelectionChange` on `<mds-table>` to receive the array of selected rows whenever the master checkbox or any individual row checkbox changes.\n\n```html\n<mds-table selectable id=\"tabella-utenti\">\n <mds-table-header>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"alice\">\n <mds-table-cell>Alice Verdi</mds-table-cell>\n <mds-table-cell>Attivo</mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"bob\">\n <mds-table-cell>Bob Neri</mds-table-cell>\n <mds-table-cell>Sospeso</mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n document.getElementById('tabella-utenti').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n });\n</script>\n```\n\n#### Actions Column - Automatic Header Cell\n\nWhen any `<mds-table-row>` exposes a `[slot=\"action\"]`, `<mds-table-header>` automatically appends a right-aligned, localized header cell (\"Action\", \"Azione\" in Italian). No extra markup is required in the header - just place your action buttons in the row slots. The column follows the rows at any time, not only on load: a table mounted empty and filled after a fetch gets it when the first row with actions arrives, and loses it when the last one goes (`<mds-table>` tells the header).\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Documento\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Dimensione\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Relazione annuale.pdf</mds-table-cell>\n <mds-table-cell>2,4 MB</mds-table-cell>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/download\"\n title=\"Scarica\"\n variant=\"primary\"\n tone=\"text\"\n ></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Batch Actions with Selection\n\nWhen `selectable` is set and the table has a `batch-action` slot, a batch-actions toolbar slides in whenever rows are selected. The toolbar is owned by `<mds-table>`: every selection change, from a row checkbox or from the master checkbox in `<mds-table-header>`, updates its count and visibility.\n\n```html\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome file\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Tipo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"doc1\">\n <mds-table-cell>contratto.pdf</mds-table-cell>\n <mds-table-cell>PDF</mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"doc2\">\n <mds-table-cell>allegato.docx</mds-table-cell>\n <mds-table-cell>Word</mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-button slot=\"batch-action\" label=\"Elimina selezionati\" variant=\"error\" tone=\"text\"></mds-button>\n <mds-button slot=\"batch-action\" label=\"Esporta\" variant=\"primary\" tone=\"outline\"></mds-button>\n</mds-table>\n```\n\n#### Styling the Actions Part\n\nThe auto-generated actions header cell is exposed as the `actions` shadow part. Target it with `::part(actions)` to adjust alignment or other visual properties.\n\n```css\nmds-table-header::part(actions) {\n text-align: center;\n min-width: 8rem;\n}\n```\n",
31424
- "3. Mistakes": "Common incorrect uses of `<mds-table-header>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-table-header>` Outside `<mds-table>`\n\n`<mds-table-header>` calls `this.host.closest('mds-table')` during load to wire up selection and action-column detection. Used standalone or inside a raw `<table>` it finds no table: the actions column is never detected, the master checkbox selects nothing, and every selection and sorting feature breaks.\n\n```html\n<!-- INCORRECT -->\n<table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n </mds-table-header>\n</table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n\n#### Do Not Slot `<mds-table-row>` Inside `<mds-table-header>`\n\nThe default slot of `<mds-table-header>` expects `<mds-table-header-cell>` elements - one per column. Slotting `<mds-table-row>` (a body-row component) into the header produces broken layout and wrong ARIA roles.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-row>\n <mds-table-cell>Cognome</mds-table-cell>\n <mds-table-cell>Email</mds-table-cell>\n </mds-table-row>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Cognome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n\n#### Do Not Set `selectable` Directly on `<mds-table-header>`\n\n`selectable` on the header is an internal prop driven by `<mds-table>` - when the table loads and whenever its `selectable` changes, it pushes its own value down. Setting it by hand on the header bypasses that synchronisation path and can leave rows and the master checkbox out of sync.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header selectable>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n\n#### Do Not Add a Manual \"Actions\" Header Cell\n\nThe component detects `[slot=\"action\"]` children in the table body and appends the localized \"Azione\" header cell automatically. Adding your own header cell for actions doubles the column and misaligns the grid.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Azioni\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Mario Rossi</mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" title=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Mario Rossi</mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" title=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Do Not Call `setSelection` from Application Code\n\n`setSelection(selectedItems, totalItems)` is an internal method called by `<mds-table>` after each row selection change. Calling it from application code duplicates the table's internal bookkeeping and can leave the checkbox in an inconsistent state. React to selection results via the `mdsTableSelectionChange` event instead.\n\n```html\n<!-- INCORRECT -->\n<script>\n const header = document.querySelector('mds-table-header');\n header.setSelection(2, 5); // do not call this from app code\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-table').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Selezione corrente:', e.detail.rows);\n });\n</script>\n```\n\n#### Do Not Use Raw `<thead>` / `<th>` Instead of the Component\n\nMixing raw HTML table elements with the Magma compound disrupts the selection wiring, the automatic actions column, and the localized labels that `<mds-table-header>` provides.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <thead>\n <tr>\n <th>Nome</th>\n <th>Email</th>\n </tr>\n </thead>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n"
31966
+ "3. Mistakes": "Common incorrect uses of `<mds-table-header>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-table-header>` Outside `<mds-table>`\n\n`<mds-table-header>` calls `this.host.closest('mds-table')` during load to wire up selection and action-column detection. Used standalone or inside a raw `<table>` it finds no table: the actions column is never detected, the master checkbox selects nothing, and every selection and sorting feature breaks.\n\n```html\n<!-- INCORRECT -->\n<table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n </mds-table-header>\n</table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n\n#### Do Not Slot `<mds-table-row>` Inside `<mds-table-header>`\n\nThe default slot of `<mds-table-header>` expects `<mds-table-header-cell>` elements - one per column. Slotting `<mds-table-row>` (a body-row component) into the header produces broken layout and wrong ARIA roles.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-row>\n <mds-table-cell>Cognome</mds-table-cell>\n <mds-table-cell>Email</mds-table-cell>\n </mds-table-row>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Cognome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n\n#### Do Not Set `selectable` Directly on `<mds-table-header>`\n\n`selectable` on the header is an internal prop driven by `<mds-table>` - when the table loads and whenever its `selectable` changes, it pushes its own value down. Setting it by hand on the header bypasses that synchronisation path and can leave rows and the master checkbox out of sync.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header selectable>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n\n#### Do Not Add a Manual \"Actions\" Header Cell\n\nThe component detects `[slot=\"action\"]` children in the table body and appends the localized \"Azione\" header cell automatically. Adding your own header cell for actions doubles the column and misaligns the grid.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Azioni\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Mario Rossi</mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" title=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Mario Rossi</mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" title=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Do Not Call `setSelection` from Application Code\n\n`setSelection(selectedItems, totalItems)` is an internal method called by `<mds-table>` every time it counts the selected rows: on load, after each row selection change and when rows come and go. Calling it from application code duplicates the table's internal bookkeeping and can leave the checkbox in an inconsistent state. React to selection results via the `mdsTableSelectionChange` event instead.\n\n```html\n<!-- INCORRECT -->\n<script>\n const header = document.querySelector('mds-table-header');\n header.setSelection(2, 5); // do not call this from app code\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-table').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Selezione corrente:', e.detail.rows);\n });\n</script>\n```\n\n#### Do Not Use Raw `<thead>` / `<th>` Instead of the Component\n\nMixing raw HTML table elements with the Magma compound disrupts the selection wiring, the automatic actions column, and the localized labels that `<mds-table-header>` provides.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <thead>\n <tr>\n <th>Nome</th>\n <th>Email</th>\n </tr>\n </thead>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n"
31425
31967
  },
31426
31968
  "props": [
31427
31969
  {
@@ -31515,10 +32057,6 @@
31515
32057
  "Promise": {
31516
32058
  "location": "global",
31517
32059
  "id": "global::Promise"
31518
- },
31519
- "HTMLMdsInputSwitchElement": {
31520
- "location": "global",
31521
- "id": "global::HTMLMdsInputSwitchElement"
31522
32060
  }
31523
32061
  },
31524
32062
  "return": "Promise<void>"
@@ -31586,8 +32124,8 @@
31586
32124
  "mds-text"
31587
32125
  ],
31588
32126
  "mds-button": [
31589
- "mds-spinner",
31590
32127
  "mds-icon",
32128
+ "mds-spinner",
31591
32129
  "mds-text"
31592
32130
  ]
31593
32131
  },
@@ -31799,8 +32337,8 @@
31799
32337
  "mds-text"
31800
32338
  ],
31801
32339
  "mds-button": [
31802
- "mds-spinner",
31803
32340
  "mds-icon",
32341
+ "mds-spinner",
31804
32342
  "mds-text"
31805
32343
  ],
31806
32344
  "mds-table-header": [
@@ -31830,7 +32368,7 @@
31830
32368
  }
31831
32369
  ],
31832
32370
  "usage": {
31833
- "1. Description": "The `<mds-table-row>` web component represents a single data row inside a [`<mds-table>`](../mds-table/AGENTS.md) (slotted through `mds-table-body`; `mds-table-header` and `mds-table-footer` are rows themselves). It wraps a set of `mds-table-cell` children, and optionally exposes a per-row selection checkbox and an aside actions menu.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-table-row>` must be slotted inside the `mds-table-body` of an `<mds-table>`; it is not used standalone and its default slot must contain `mds-table-cell` elements, not arbitrary markup.\n- **Parent-driven configuration**: `interactive`, `selectable`, and `overlayActions` are set by the parent `<mds-table>` on every row, so rows stay in sync with table state rather than being configured one by one.\n- **Selection reporting**: When `selectable` is on, the row renders a leading selection checkbox; toggling it updates the row's `selected` prop and tells the table to recompute and emit the table-level selection event.\n- **Selected as two-way state**: `selected` can be read and set by the parent to drive bulk select-all behavior.\n- **Actions menu**: An `action`-named slot, when present, renders an actions cell that floats correctly over the scrolling row.\n- **Localized accessibility labels**: The selection switch's title is localized (Select/Deselect row) across el/en/es/it.\n\n#### Properties & Visual Configurations\n\nMost props are orchestrated by the parent table rather than set directly by consumers:\n\n- **`interactive`**: mirrors the table's interactive mode (hover highlight); normally inherited from `<mds-table>` rather than set per row.\n- **`selectable`**: enables the leading selection switch; toggled by the table so all rows gain or lose selection together.\n- **`overlayActions`**: set by the table when the row content overflows horizontally, switching the actions menu to an overlay rendering so it stays reachable while scrolling.\n- **`selected`**: the row's current selection state; read and written by the parent for select-all and batch operations.\n- **`value`**: the identifying payload reported back in the table's selection event for this row - set this to the business key (e.g. record id) you need when handling selections.\n",
32371
+ "1. Description": "The `<mds-table-row>` web component represents a single data row inside a [`<mds-table>`](../mds-table/AGENTS.md) (slotted through `mds-table-body`; `mds-table-header` and `mds-table-footer` are rows themselves). It wraps a set of `mds-table-cell` children, and optionally exposes a per-row selection checkbox and an aside actions menu.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-table-row>` must be slotted inside the `mds-table-body` of an `<mds-table>`; it is not used standalone and its default slot must contain `mds-table-cell` elements, not arbitrary markup.\n- **Parent-driven configuration**: `interactive`, `selectable`, and `overlayActions` are set by the parent `<mds-table>` on every row, so rows stay in sync with table state rather than being configured one by one.\n- **Selection reporting**: When `selectable` is on, the row renders a leading selection checkbox; toggling it updates the row's `selected` prop and tells the table to recompute and emit the table-level selection event.\n- **Selected as two-way state**: `selected` can be read and set by the parent to drive bulk select-all behavior.\n- **Actions menu**: An `action`-named slot, when present, renders an actions cell that floats correctly over the scrolling row.\n- **Localized accessibility labels**: The selection switch's title is localized (Select/Deselect row) across el/en/es/it.\n\n#### Properties & Visual Configurations\n\nMost props are orchestrated by the parent table rather than set directly by consumers:\n\n- **`interactive`**: mirrors the table's interactive mode (hover highlight); normally inherited from `<mds-table>` rather than set per row.\n- **`selectable`**: enables the leading selection switch; toggled by the table so all rows gain or lose selection together.\n- **`overlayActions`**: set by the table when the row content overflows horizontally, switching the actions menu to an overlay rendering so it stays reachable while scrolling.\n- **`selected`**: the row's current selection state; read and written by the parent for select-all and batch operations. Write it in the markup for a row that starts selected: the table counts it on load, without an `mdsTableSelectionChange`.\n- **`value`**: the identifying payload reported back in the table's selection event for this row - set this to the business key (e.g. record id) you need when handling selections.\n",
31834
32372
  "2. Examples": "Correct and idiomatic ways to use the `<mds-table-row>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Row with Data Cells\n\nThe minimal form: slot one or more [`mds-table-cell`](../mds-table-cell/AGENTS.md) elements into the default slot. Always place `<mds-table-row>` inside [`mds-table-body`](../mds-table-body/AGENTS.md) - never standalone, and never inside `mds-table-header` / `mds-table-footer`, which are rows themselves.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">mario.rossi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">12 ottobre 1985</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Luigi Verdi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">luigi.verdi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">3 marzo 1993</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Row with Per-Row Actions\n\nSlot one or more [`mds-button`](../mds-button/AGENTS.md) elements into the `action` slot to add a contextual actions menu that slides in on row hover. Use icon-only buttons with `aria-label` (or `title`) because the label has no space.\n\n```html\n<mds-table-row value=\"42\">\n <mds-table-cell><mds-text typography=\"detail\">Documento riservato.pdf</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">2 MB</mds-text></mds-table-cell>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/download\"\n title=\"Scarica\"\n variant=\"primary\"\n tone=\"text\"\n ></mds-button>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/delete\"\n title=\"Elimina\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n</mds-table-row>\n```\n\n#### Row with Identifying `value`\n\nSet `value` to the business key (record id or slug) that the parent table should include in the `mdsTableSelectionChange` event detail. This wires the visual row to the data layer without any manual DOM traversal.\n\n```html\n<mds-table selectable>\n <mds-table-body>\n <mds-table-row value=\"user-101\">\n <mds-table-cell><mds-text typography=\"detail\">Carla Bianchi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">carla.bianchi@example.com</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"user-102\">\n <mds-table-cell><mds-text typography=\"detail\">Federica Neri</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">federica.neri@example.com</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Selectable Table - Reading the Selection Event\n\nWhen the parent `<mds-table>` sets `selectable`, each row renders a leading checkbox automatically. Listen for `mdsTableSelectionChange` on the table - do not wire per-row events.\n\n```html\n<mds-table id=\"utenti\" selectable>\n <mds-table-body>\n <mds-table-row value=\"101\">\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"102\">\n <mds-table-cell><mds-text typography=\"detail\">Luigi Verdi</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n document.getElementById('utenti').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n });\n</script>\n```\n\n#### Programmatic Selection\n\n`selected` is mutable and reflected. Set it from JavaScript to restore a previously saved selection state. The parent table follows it: it emits `mdsTableSelectionChange` and updates the header checkbox and the batch-action bar, once for the rows changed together. For bulk \"select all\" use the table's `selectAll()`.\n\n```html\n<mds-table selectable id=\"tabella-record\">\n <mds-table-body>\n <mds-table-row id=\"riga-principale\" value=\"rec-1\">\n <mds-table-cell><mds-text typography=\"detail\">Record principale</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n // Select the row programmatically (e.g. after restoring from storage)\n document.getElementById('riga-principale').selected = true;\n</script>\n```\n\n#### Interactive Table (Hover Highlight)\n\nSet `interactive` on the parent `<mds-table>` to enable per-row hover highlights. The prop is mirrored to each row by the table - do not set it on individual rows.\n\n```html\n<mds-table interactive>\n <mds-table-body>\n <mds-table-row value=\"p-01\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica 01</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">In lavorazione</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"p-02\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica 02</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Completata</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Styling Customization\n\nA row takes its colours from the parent `mds-table-body` (and `mds-table`), and its hover, selected and sorted colours and the spacing of its actions follow its states. Restyle the rows through the public `--mds-table-body-*` or `--mds-table-*` properties of the parents. Use the semantic color roles wrapped in `rgb(var(--magma-<role>))` so dark mode and high-contrast modes stay consistent.\n\n```css\n/* Branded colours for the rows of a table */\n.tabella-brand mds-table-body {\n --mds-table-body-background: rgb(var(--magma-surface-raised));\n --mds-table-body-color: rgb(var(--magma-text-default));\n}\n```\n\nThe one public custom property of the row, `--mds-table-row-actions-background`, is read-only: it is the background the actions box paints in the current state of the row (at rest, on hover, while a column sorts a selectable table). Content of the `action` slot reads it to paint the same colour when it moves out of the box, for example a status that follows the part of a tall row on screen. Read it, never set it: the box sets it itself, so a value set from outside changes nothing.\n\n```html\n<mds-table interactive>\n <mds-table-body>\n <mds-table-row value=\"p-01\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica 01</mds-text></mds-table-cell>\n <mds-text slot=\"action\" typography=\"detail\" class=\"bg-(--mds-table-row-actions-background)\">Copiato</mds-text>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n",
31835
32373
  "3. Mistakes": "Common incorrect uses of `<mds-table-row>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-table-row>` Standalone\n\n`<mds-table-row>` is a compound child component and must be slotted inside the [`mds-table-body`](../mds-table-body/AGENTS.md) of an [`mds-table`](../mds-table/AGENTS.md). Using it outside the table subtree breaks layout and the internal parent-child communication that drives selection and interactive state.\n\n```html\n<!-- INCORRECT -->\n<div class=\"my-list\">\n <mds-table-row>\n <mds-table-cell>Mario Rossi</mds-table-cell>\n </mds-table-row>\n</div>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Do Not Put Arbitrary HTML in the Default Slot\n\nThe default slot of `<mds-table-row>` accepts only [`mds-table-cell`](../mds-table-cell/AGENTS.md) elements. Slotting raw `<td>`, `<div>`, or other markup breaks the table layout model and the sort/selection logic that relies on `mds-table-cell` identity.\n\n```html\n<!-- INCORRECT -->\n<mds-table-row>\n <td>Mario Rossi</td>\n <div>mario.rossi@example.com</div>\n</mds-table-row>\n\n<!-- CORRECT -->\n<mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">mario.rossi@example.com</mds-text></mds-table-cell>\n</mds-table-row>\n```\n\n#### Do Not Set `interactive` or `selectable` Directly on Individual Rows\n\nBoth props are orchestrated by the parent `<mds-table>` and propagated to every row automatically. Setting them per-row creates a desynchronized state where some rows behave differently from others, and the table's own state machine does not know about the override.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-body>\n <mds-table-row interactive selectable>\n <mds-table-cell><mds-text typography=\"detail\">Pratica 01</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table interactive selectable>\n <mds-table-body>\n <mds-table-row value=\"p-01\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica 01</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Do Not Listen for Row Events to Track Selection - Use the Table Event\n\n`<mds-table-row>` does not emit a public selection event. The table-level `mdsTableSelectionChange` event is the single aggregated source of truth for which rows are selected. Polling each row's `selected` attribute via MutationObserver or querying the DOM on every click is fragile and bypasses the table's own selection bookkeeping.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelectorAll('mds-table-row').forEach((row) => {\n row.addEventListener('click', () => {\n console.log('selezionato:', row.selected);\n });\n });\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-table').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n });\n</script>\n```\n\n#### Do Not Slot Icon-Only Action Buttons Without an Accessible Name\n\nButtons in the `action` slot render without visible labels. An `<mds-button>` that has neither `label` nor `aria-label` / `title` falls back to the last segment of its icon slug (`delete`), which names the icon, not the action. Always provide `title` or `aria-label` on every action button.\n\n```html\n<!-- INCORRECT -->\n<mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Documento.pdf</mds-text></mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-table-row>\n\n<!-- CORRECT -->\n<mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Documento.pdf</mds-text></mds-table-cell>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/delete\"\n title=\"Elimina documento\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n</mds-table-row>\n```\n\n#### Do Not Override Row Appearance with Inline Styles or Undocumented Selectors\n\n`mds-table-row` has no public CSS custom property and no shadow part: restyle the rows through the public `--mds-table-body-*` or `--mds-table-*` properties of the parents. Targeting internal shadow parts or setting `background-color` / `color` directly on the host element bypasses the interactive and selected state logic and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-table-row {\n background-color: rgb(var(--magma-surface-raised));\n color: rgb(var(--magma-text-default));\n}\nmds-table-row::part(actions) {\n gap: 4px;\n}\n\n/* CORRECT */\nmds-table-body {\n --mds-table-body-background: rgb(var(--magma-surface-raised));\n --mds-table-body-color: rgb(var(--magma-text-default));\n}\n```\n"
31836
32374
  },
@@ -33241,8 +33779,8 @@
33241
33779
  "mds-button"
33242
33780
  ],
33243
33781
  "mds-button": [
33244
- "mds-spinner",
33245
33782
  "mds-icon",
33783
+ "mds-spinner",
33246
33784
  "mds-text"
33247
33785
  ]
33248
33786
  },
@@ -35087,8 +35625,8 @@
35087
35625
  "mds-button"
35088
35626
  ],
35089
35627
  "mds-button": [
35090
- "mds-spinner",
35091
35628
  "mds-icon",
35629
+ "mds-spinner",
35092
35630
  "mds-text"
35093
35631
  ]
35094
35632
  },
@@ -35298,8 +35836,8 @@
35298
35836
  "mds-button"
35299
35837
  ],
35300
35838
  "mds-button": [
35301
- "mds-spinner",
35302
35839
  "mds-icon",
35840
+ "mds-spinner",
35303
35841
  "mds-text"
35304
35842
  ]
35305
35843
  },
@@ -35847,9 +36385,9 @@
35847
36385
  }
35848
36386
  ],
35849
36387
  "usage": {
35850
- "1. Description": "The `<mds-zero>` web component is the empty-state (zero-data) panel of the Magma Design System: a centered, vertically stacked layout that pairs an illustration, explanatory copy, and a call-to-action to guide users when a list, search, or section has no content to show. It is a pure structural container with no props - composition happens entirely through its slots.\n\n#### Semantic Behavior\n\n- **Three-zone layout**: The host stacks its content vertically and centered - the default slot (the visual) on top, the `content` zone in the middle, and the `action` zone in a footer at the bottom.\n- **Default slot is the visual**: The unnamed default slot holds the illustration or image; it is meant for an `mds-img`/`img`, not text.\n- **Content zone is centered text**: The `content` slot is centered and constrained by a max-width, so headings and descriptions read as a focused message block.\n- **Action zone auto-centers children**: Elements placed in `slot=\"action\"` are horizontally centered within the footer, so a single primary button sits centered by default.\n- **Themed surface**: The host renders a neutral rounded surface that picks up theme, contrast, and reduced-motion preferences.\n\n#### Properties & Visual Configurations\n\n`<mds-zero>` exposes no props; all configuration is done through slot composition and one CSS custom property.\n\n- **`content` vs. `action` slots**: Put the message (title + description, typically `mds-text`) in `slot=\"content\"`, and the recovery action (typically a single `mds-button`) in `slot=\"action\"`. Use the default slot only for the illustration.\n- **`--mds-zero-contents-max-width`**: Caps the width of the centered text block (default `400px`) so long descriptions wrap into a balanced column rather than spanning the full panel.\n\nThe `contents` and `actions` shadow parts expose the two wrapper zones for consumers that need to override their layout from outside the shadow boundary.\n",
35851
- "2. Examples": "Correct and idiomatic ways to use the `<mds-zero>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Full Empty-State Panel\n\nThe canonical form. Pair an illustration in the default slot with a heading and description in `slot=\"content\"`, then provide a recovery action in `slot=\"action\"`.\n\n```html\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty-list.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"h5\" slot=\"content\">Nessun elemento trovato</mds-text>\n <mds-text typography=\"detail\" slot=\"content\">\n Non ci sono elementi che corrispondono alla tua ricerca.\n Modifica i filtri o crea un nuovo elemento.\n </mds-text>\n <mds-button\n slot=\"action\"\n label=\"Crea elemento\"\n variant=\"primary\"\n tone=\"strong\"\n size=\"lg\"\n ></mds-button>\n</mds-zero>\n```\n\n#### Illustration Only (No Action)\n\nWhen there is no meaningful recovery action, omit `slot=\"action\"` entirely. The action zone collapses cleanly.\n\n```html\n<mds-zero>\n <mds-img src=\"./assets/illustrations/no-results.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"h5\" slot=\"content\">Nessun risultato</mds-text>\n <mds-text typography=\"detail\" slot=\"content\">\n Prova a modificare i criteri di ricerca per trovare cio che cerchi.\n </mds-text>\n</mds-zero>\n```\n\n#### Message Without Illustration\n\nWhen no illustration asset is available, omit the default slot. The component stacks the content and action zones directly.\n\n```html\n<mds-zero>\n <mds-text typography=\"h5\" slot=\"content\">La cartella e vuota</mds-text>\n <mds-text typography=\"detail\" slot=\"content\">\n Carica i tuoi file per iniziare a condividerli con il team.\n </mds-text>\n <mds-button\n slot=\"action\"\n label=\"Carica file\"\n icon=\"mi/baseline/upload\"\n variant=\"primary\"\n tone=\"strong\"\n ></mds-button>\n</mds-zero>\n```\n\n#### Multiple Actions\n\nWhen two peer actions are offered - for example a primary and a secondary CTA - place both `<mds-button>` elements in `slot=\"action\"`. The action zone centers and spaces them automatically.\n\n```html\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty-inbox.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"h5\" slot=\"content\">Nessun messaggio</mds-text>\n <mds-text typography=\"detail\" slot=\"content\">\n La tua casella e vuota. Inizia una nuova conversazione o invita i tuoi colleghi.\n </mds-text>\n <mds-button\n slot=\"action\"\n label=\"Nuovo messaggio\"\n variant=\"primary\"\n tone=\"strong\"\n ></mds-button>\n <mds-button\n slot=\"action\"\n label=\"Invita colleghi\"\n variant=\"primary\"\n tone=\"outline\"\n ></mds-button>\n</mds-zero>\n```\n\n#### Constraining the Text Block Width\n\nUse `--mds-zero-contents-max-width` when the panel is wide and the default `400px` cap produces too narrow a text column, or when you want a tighter column on a compact layout.\n\n```css\n.wide-dashboard mds-zero {\n --mds-zero-contents-max-width: 560px;\n}\n\n.compact-sidebar mds-zero {\n --mds-zero-contents-max-width: 280px;\n}\n```\n\n#### Overriding Zone Layout via Shadow Parts\n\nUse `::part(contents)` or `::part(actions)` only when you need to change the zone's layout itself - for example aligning the content left inside a side-panel context. Prefer `--mds-zero-contents-max-width` for width adjustments.\n\n```css\n/* Left-align content for a narrow side panel */\n.side-panel mds-zero::part(contents) {\n align-items: flex-start;\n text-align: left;\n}\n```\n",
35852
- "3. Mistakes": "Common incorrect uses of `<mds-zero>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Put Text in the Default Slot\n\nThe default slot is reserved for the illustration or image. Text placed there is not constrained by the `contents` max-width, is not centered consistently, and falls outside the structured three-zone layout. Put headings and descriptions in `slot=\"content\"`.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-text typography=\"h5\">Nessun elemento</mds-text>\n <mds-text typography=\"detail\">Crea il primo elemento per iniziare.</mds-text>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-text typography=\"h5\" slot=\"content\">Nessun elemento</mds-text>\n <mds-text typography=\"detail\" slot=\"content\">Crea il primo elemento per iniziare.</mds-text>\n</mds-zero>\n```\n\n#### Do Not Put the Illustration in `slot=\"content\"`\n\nPlacing an image or `<mds-img>` inside `slot=\"content\"` wraps it in the max-width-constrained, centered-text zone. The default slot renders above that zone with full layout freedom and is the correct home for illustrations.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\" slot=\"content\"></mds-img>\n <mds-text typography=\"h5\" slot=\"content\">Nessun documento</mds-text>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"h5\" slot=\"content\">Nessun documento</mds-text>\n</mds-zero>\n```\n\n#### Do Not Put the CTA in `slot=\"content\"`\n\nA button placed in `slot=\"content\"` ends up inside the centered-text block rather than the footer zone; it loses the auto-centering and the correct spacing the `actions` zone provides. Use `slot=\"action\"` for any interactive control.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"h5\" slot=\"content\">Nessun progetto</mds-text>\n <mds-button label=\"Nuovo progetto\" variant=\"primary\" slot=\"content\"></mds-button>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"h5\" slot=\"content\">Nessun progetto</mds-text>\n <mds-button label=\"Nuovo progetto\" variant=\"primary\" slot=\"action\"></mds-button>\n</mds-zero>\n```\n\n#### Do Not Use a Raw `<button>` or `<a>` in the Action Slot\n\nThe action slot is designed for `<mds-button>`. A raw `<button>` or `<a>` will not inherit Magma theming, focus styles, or size tokens. Use `<mds-button>` with `href` if link behavior is needed.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"h5\" slot=\"content\">Nessun report</mds-text>\n <button slot=\"action\" class=\"btn-primary\">Crea report</button>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"h5\" slot=\"content\">Nessun report</mds-text>\n <mds-button slot=\"action\" label=\"Crea report\" variant=\"primary\" tone=\"strong\"></mds-button>\n</mds-zero>\n```\n\n#### Do Not Pierce Shadow DOM to Style Internal Zones\n\n`::part(contents)` and `::part(actions)` are the documented customization surface for the wrapper zones. Do not target internal class names (`.contents`, `.actions`) via `>>>` or `/deep/` - those are implementation details that can change without notice.\n\n```css\n/* INCORRECT */\nmds-zero >>> .contents {\n max-width: 600px;\n}\n\n/* CORRECT */\nmds-zero {\n --mds-zero-contents-max-width: 600px;\n}\n/* or, for layout overrides: */\nmds-zero::part(contents) {\n align-items: flex-start;\n}\n```\n"
36388
+ "1. Description": "The `<mds-zero>` web component is the empty-state (zero-data) panel of the Magma Design System: a centered, vertically stacked layout that pairs an illustration, explanatory copy, and a call-to-action to guide users when a list, search, or section has no content to show. It is a pure structural container with no props - composition happens entirely through its slots.\n\n#### Semantic Behavior\n\n- **Three-zone layout**: The host stacks its content vertically and centered - the default slot (the visual) on top, the `content` zone in the middle, and the `action` zone in a footer at the bottom - with `--magma-rhythm-content-actions` (600) between the zones.\n- **One inset, shared by the zones**: The host pads its zones once, with `--magma-rhythm-inset` (600) on every side, the inset of a container of a part (`rhythm/inset`, `rhythm/shared-inset` in the design language). With no action the footer takes no room, so the inset stays the same at the bottom.\n- **Default slot is the visual**: The unnamed default slot holds the illustration or image; it is meant for an `mds-img`/`img`, not text.\n- **Content zone is centered text**: The `content` slot is centered, constrained by a max-width, and sets its children `--magma-rhythm-title-content` (300) apart, so a title and its description read as one message with no wrapper of yours (`rhythm/title-content`).\n- **Action zone auto-centers children**: Elements placed in `slot=\"action\"` are horizontally centered within the footer, `--magma-rhythm-inline` (300) apart, so a single primary button sits centered by default.\n- **A muted surface**: The host paints `--magma-surface-muted`, a step under the page in light and in dark, on the plane where the items would stand; it needs no dark correction, and it picks up the contrast (a ring) and reduced-motion preferences.\n\n#### Properties & Visual Configurations\n\n`<mds-zero>` exposes no props; all configuration is done through slot composition and one CSS custom property.\n\n- **`content` vs. `action` slots**: Put the message in `slot=\"content\"`: a title by its role, `mds-text typography=\"part\"` with the `tag` of its place in the outline (`h2` under the title of the page, `h3` in a section, `h1` with `typography=\"page\"` when the panel takes the place of the page), then the description in `typography=\"detail\"`. Put the recovery action (typically a single `mds-button`) in `slot=\"action\"`. Use the default slot only for the illustration.\n- **`--mds-zero-contents-max-width`**: Caps the width of the centered text block (default `400px`) so long descriptions wrap into a balanced column rather than spanning the full panel.\n\nThe `contents` and `actions` shadow parts expose the two wrapper zones for consumers that need to override their layout from outside the shadow boundary.\n",
36389
+ "2. Examples": "Correct and idiomatic ways to use the `<mds-zero>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md). Which panel an empty part takes, and what it says, is the pattern `empty-state`.\n\nThe title of the panel is written by its role, `typography=\"part\"` (`titles/part` of the design language), with the `tag` of its place in the outline: `h2` under the title of the page, `h3` inside a section. Put the title and the description straight in `slot=\"content\"`: the panel sets them apart itself.\n\n#### Full Empty-State Panel\n\nThe canonical form, the first use: an illustration in the default slot, a title and a description in `slot=\"content\"`, and the action that adds the first item in `slot=\"action\"`.\n\n```html\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty-list.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessuna delega</mds-text>\n <mds-text typography=\"detail\" tag=\"p\" slot=\"content\">\n Con una delega un familiare o un professionista presenta le richieste a tuo nome.\n Aggiungi la prima per iniziare.\n </mds-text>\n <mds-button\n slot=\"action\"\n label=\"Nuova delega\"\n variant=\"primary\"\n tone=\"strong\"\n size=\"lg\"\n ></mds-button>\n</mds-zero>\n```\n\n#### Filled by Others (No Action)\n\nWhen the person has nothing to do here, omit `slot=\"action\"` entirely and say who fills the part, and when. The action zone takes no room, so the inset stays the same on every side.\n\n```html\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty-folder.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun documento</mds-text>\n <mds-text typography=\"detail\" tag=\"p\" slot=\"content\">\n L'ufficio anagrafe aggiunge qui i documenti della pratica quando la prende in carico.\n </mds-text>\n</mds-zero>\n```\n\n#### Message Without Illustration\n\nWhen no illustration asset is available, omit the default slot. The component stacks the content and action zones directly.\n\n```html\n<mds-zero>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun file</mds-text>\n <mds-text typography=\"detail\" tag=\"p\" slot=\"content\">\n Carica i tuoi file per iniziare a condividerli con il team.\n </mds-text>\n <mds-button\n slot=\"action\"\n label=\"Carica file\"\n icon=\"mi/baseline/upload\"\n variant=\"primary\"\n tone=\"strong\"\n ></mds-button>\n</mds-zero>\n```\n\n#### Multiple Actions\n\nWhen two peer actions are offered - for example a primary and a secondary CTA - place both `<mds-button>` elements in `slot=\"action\"`. The action zone centers them and sets them `--magma-rhythm-inline` apart.\n\n```html\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty-inbox.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun messaggio</mds-text>\n <mds-text typography=\"detail\" tag=\"p\" slot=\"content\">\n Inizia una nuova conversazione o invita i tuoi colleghi.\n </mds-text>\n <mds-button\n slot=\"action\"\n label=\"Nuovo messaggio\"\n variant=\"primary\"\n tone=\"strong\"\n ></mds-button>\n <mds-button\n slot=\"action\"\n label=\"Invita colleghi\"\n variant=\"primary\"\n tone=\"outline\"\n ></mds-button>\n</mds-zero>\n```\n\n#### In Place of a Missing Page\n\nWhen the panel takes the place of the whole page (the thing asked for does not exist), its title is the title of the page: `typography=\"page\"` with `tag=\"h1\"`, and its action leads back to the list.\n\n```html\n<main class=\"page-frame py-between-sections\">\n <mds-zero>\n <mds-text typography=\"page\" tag=\"h1\" slot=\"content\">Richiesta non trovata</mds-text>\n <mds-text typography=\"detail\" tag=\"p\" slot=\"content\">\n La richiesta 2026/0412 non esiste: cercala nell'elenco delle richieste.\n </mds-text>\n <mds-button slot=\"action\" label=\"Vai alle richieste\" href=\"/richieste\"></mds-button>\n </mds-zero>\n</main>\n```\n\n#### Constraining the Text Block Width\n\nUse `--mds-zero-contents-max-width` when the panel is wide and the default `400px` cap produces too narrow a text column, or when you want a tighter column on a compact layout.\n\n```css\n.wide-dashboard mds-zero {\n --mds-zero-contents-max-width: 560px;\n}\n\n.compact-sidebar mds-zero {\n --mds-zero-contents-max-width: 280px;\n}\n```\n\n#### Overriding Zone Layout via Shadow Parts\n\nUse `::part(contents)` or `::part(actions)` only when you need to change the zone's layout itself - for example aligning the content left inside a side-panel context. Prefer `--mds-zero-contents-max-width` for width adjustments.\n\n```css\n/* Left-align content for a narrow side panel */\n.side-panel mds-zero::part(contents) {\n align-items: flex-start;\n text-align: left;\n}\n```\n",
36390
+ "3. Mistakes": "Common incorrect uses of `<mds-zero>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Put Text in the Default Slot\n\nThe default slot is reserved for the illustration or image. Text placed there is not constrained by the `contents` max-width, is not centered consistently, and falls outside the structured three-zone layout. Put headings and descriptions in `slot=\"content\"`.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-text typography=\"part\" tag=\"h2\">Nessun elemento</mds-text>\n <mds-text typography=\"detail\">Crea il primo elemento per iniziare.</mds-text>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun elemento</mds-text>\n <mds-text typography=\"detail\" slot=\"content\">Crea il primo elemento per iniziare.</mds-text>\n</mds-zero>\n```\n\n#### Do Not Title the Panel by Level\n\nA level picked by its size (`h5`, `h6`) says nothing of what the title names, and its tag follows the style instead of the outline of the page. The title of the panel is a part (`titles/part` of the design language): `typography=\"part\"`, with the `tag` of its place, `h2` under the title of the page, `h3` in a section.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-text typography=\"h5\" slot=\"content\">Nessuna richiesta da gestire</mds-text>\n <mds-text typography=\"detail\" slot=\"content\">Le nuove arrivano qui appena un cittadino le invia.</mds-text>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessuna richiesta da gestire</mds-text>\n <mds-text typography=\"detail\" tag=\"p\" slot=\"content\">Le nuove arrivano qui appena un cittadino le invia.</mds-text>\n</mds-zero>\n```\n\n#### Do Not Wrap the Content to Space It\n\nThe content zone already sets its children `--magma-rhythm-title-content` apart. A wrapper with its own gap adds nothing but a second place where the space is decided; put the title and the description straight in `slot=\"content\"`.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <div slot=\"content\" class=\"grid gap-title-content\">\n <mds-text typography=\"part\" tag=\"h2\">Nessuna delega</mds-text>\n <mds-text typography=\"detail\" tag=\"p\">Aggiungi la prima per iniziare.</mds-text>\n </div>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessuna delega</mds-text>\n <mds-text typography=\"detail\" tag=\"p\" slot=\"content\">Aggiungi la prima per iniziare.</mds-text>\n</mds-zero>\n```\n\n#### Do Not Put the Illustration in `slot=\"content\"`\n\nPlacing an image or `<mds-img>` inside `slot=\"content\"` wraps it in the max-width-constrained, centered-text zone. The default slot renders above that zone with full layout freedom and is the correct home for illustrations.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\" slot=\"content\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun documento</mds-text>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun documento</mds-text>\n</mds-zero>\n```\n\n#### Do Not Put the CTA in `slot=\"content\"`\n\nA button placed in `slot=\"content\"` ends up inside the centered-text block rather than the footer zone; it loses the auto-centering and the correct spacing the `actions` zone provides. Use `slot=\"action\"` for any interactive control.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun progetto</mds-text>\n <mds-button label=\"Nuovo progetto\" variant=\"primary\" slot=\"content\"></mds-button>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun progetto</mds-text>\n <mds-button label=\"Nuovo progetto\" variant=\"primary\" slot=\"action\"></mds-button>\n</mds-zero>\n```\n\n#### Do Not Use a Raw `<button>` or `<a>` in the Action Slot\n\nThe action slot is designed for `<mds-button>`. A raw `<button>` or `<a>` will not inherit Magma theming, focus styles, or size tokens. Use `<mds-button>` with `href` if link behavior is needed.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun report</mds-text>\n <button slot=\"action\" class=\"btn-primary\">Crea report</button>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun report</mds-text>\n <mds-button slot=\"action\" label=\"Crea report\" variant=\"primary\" tone=\"strong\"></mds-button>\n</mds-zero>\n```\n\n#### Do Not Pierce Shadow DOM to Style Internal Zones\n\n`::part(contents)` and `::part(actions)` are the documented customization surface for the wrapper zones. Do not target internal class names (`.contents`, `.actions`) via `>>>` or `/deep/` - those are implementation details that can change without notice.\n\n```css\n/* INCORRECT */\nmds-zero >>> .contents {\n max-width: 600px;\n}\n\n/* CORRECT */\nmds-zero {\n --mds-zero-contents-max-width: 600px;\n}\n/* or, for layout overrides: */\nmds-zero::part(contents) {\n align-items: flex-start;\n}\n```\n"
35853
36391
  },
35854
36392
  "props": [],
35855
36393
  "methods": [],
@@ -35916,7 +36454,7 @@
35916
36454
  "path": "src/type/tone.ts"
35917
36455
  },
35918
36456
  "src/type/text.ts::TypographyTruncateType": {
35919
- "declaration": "\"none\" | \"all\" | \"word\"",
36457
+ "declaration": "\"all\" | \"none\" | \"word\"",
35920
36458
  "docstring": "",
35921
36459
  "path": "src/type/text.ts"
35922
36460
  },
@@ -35935,6 +36473,11 @@
35935
36473
  "docstring": "",
35936
36474
  "path": "src/type/typography.ts"
35937
36475
  },
36476
+ "src/type/text.ts::TypographyHeadingTagType": {
36477
+ "declaration": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\"",
36478
+ "docstring": "",
36479
+ "path": "src/type/text.ts"
36480
+ },
35938
36481
  "src/components/mds-accordion-item/meta/event-detail.ts::MdsAccordionItemEventDetail": {
35939
36482
  "declaration": "export interface MdsAccordionItemEventDetail {\n id: string;\n selected: boolean;\n}",
35940
36483
  "docstring": "",
@@ -35985,6 +36528,11 @@
35985
36528
  "docstring": "",
35986
36529
  "path": "src/type/tone.ts"
35987
36530
  },
36531
+ "src/components/mds-banner/meta/types.ts::BannerTypographyType": {
36532
+ "declaration": "\"h5\" | \"h6\"",
36533
+ "docstring": "",
36534
+ "path": "src/components/mds-banner/meta/types.ts"
36535
+ },
35988
36536
  "src/components/mds-benchmark-bar/meta/types.ts::BenchmarkBarTypographyType": {
35989
36537
  "declaration": "export type BenchmarkBarTypographyType = 'option' | 'label';",
35990
36538
  "docstring": "",
@@ -36066,7 +36614,7 @@
36066
36614
  "path": "src/type/button.ts"
36067
36615
  },
36068
36616
  "src/type/button.ts::ButtonVariantType": {
36069
- "declaration": "export type ButtonVariantType =\n | 'apple'\n | 'google'\n | ThemeLuminanceVariantType\n | ThemeBrandVariantType\n | ThemeStatusVariantType;",
36617
+ "declaration": "export type ButtonVariantType =\n 'apple' | 'google' | ThemeLuminanceVariantType | ThemeBrandVariantType | ThemeStatusVariantType;",
36070
36618
  "docstring": "",
36071
36619
  "path": "src/type/button.ts"
36072
36620
  },
@@ -36085,11 +36633,21 @@
36085
36633
  "docstring": "",
36086
36634
  "path": "src/type/button.ts"
36087
36635
  },
36636
+ "src/type/button.ts::ButtonCurrentType": {
36637
+ "declaration": "export type ButtonCurrentType = boolean | (typeof buttonCurrentDictionary)[number];",
36638
+ "docstring": "",
36639
+ "path": "src/type/button.ts"
36640
+ },
36088
36641
  "src/type/button.ts::ButtonDropdownVariantType": {
36089
- "declaration": "export type ButtonDropdownVariantType =\n | ThemeLuminanceVariantType\n | ThemeBrandVariantType\n | ThemeStatusVariantType;",
36642
+ "declaration": "export type ButtonDropdownVariantType =\n ThemeLuminanceVariantType | ThemeBrandVariantType | ThemeStatusVariantType;",
36090
36643
  "docstring": "",
36091
36644
  "path": "src/type/button.ts"
36092
36645
  },
36646
+ "src/components/mds-calendar/meta/types.ts::CalendarRangeEndType": {
36647
+ "declaration": "export type CalendarRangeEndType = 'start' | 'end';",
36648
+ "docstring": "",
36649
+ "path": "src/components/mds-calendar/meta/types.ts"
36650
+ },
36093
36651
  "src/components/mds-calendar-cell/meta/types.ts::CalendarCellType": {
36094
36652
  "declaration": "export type CalendarCellType = 'other' | 'current' | 'weekend';",
36095
36653
  "docstring": "",
@@ -36166,12 +36724,12 @@
36166
36724
  "path": "src/components/mds-filter-item/meta/event-detail.ts"
36167
36725
  },
36168
36726
  "src/type/header-bar.ts::HeaderBarMenuType": {
36169
- "declaration": "\"none\" | \"all\" | \"desktop\" | \"mobile\"",
36727
+ "declaration": "\"all\" | \"none\" | \"desktop\" | \"mobile\"",
36170
36728
  "docstring": "",
36171
36729
  "path": "src/type/header-bar.ts"
36172
36730
  },
36173
36731
  "src/type/header-bar.ts::HeaderBarNavType": {
36174
- "declaration": "\"none\" | \"all\" | \"desktop\" | \"mobile\"",
36732
+ "declaration": "\"all\" | \"none\" | \"desktop\" | \"mobile\"",
36175
36733
  "docstring": "",
36176
36734
  "path": "src/type/header-bar.ts"
36177
36735
  },
@@ -36236,7 +36794,7 @@
36236
36794
  "path": "src/type/variant.ts"
36237
36795
  },
36238
36796
  "src/type/input.ts::InputTextType": {
36239
- "declaration": "\"number\" | \"text\" | \"time\" | \"email\" | \"tel\" | \"url\" | \"date\" | \"password\" | \"search\" | \"textarea\" | \"cc\" | \"cf\" | \"isbn\" | \"piva\"",
36797
+ "declaration": "\"number\" | \"time\" | \"text\" | \"email\" | \"tel\" | \"url\" | \"date\" | \"password\" | \"search\" | \"textarea\" | \"color\" | \"cc\" | \"cf\" | \"isbn\" | \"piva\"",
36240
36798
  "docstring": "",
36241
36799
  "path": "src/type/input.ts"
36242
36800
  },
@@ -36265,6 +36823,11 @@
36265
36823
  "docstring": "",
36266
36824
  "path": "src/components.d.ts"
36267
36825
  },
36826
+ "src/components/mds-input-range/meta/event-detail.ts::MdsInputRangeValuesEventDetail": {
36827
+ "declaration": "export interface MdsInputRangeValuesEventDetail {\n /**\n * The values of the `mds-input-range-value` children, one per thumb, in order from the lowest:\n * the order of their thumbs on the track and of their entries in the form.\n */\n values: number[];\n}",
36828
+ "docstring": "",
36829
+ "path": "src/components/mds-input-range/meta/event-detail.ts"
36830
+ },
36268
36831
  "src/type/variant.ts::ThemeStatusVariantType": {
36269
36832
  "declaration": "\"info\" | \"error\" | \"success\" | \"warning\"",
36270
36833
  "docstring": "",
@@ -36426,7 +36989,7 @@
36426
36989
  "path": "src/type/preference.ts"
36427
36990
  },
36428
36991
  "src/type/preference.ts::PreferenceThemeSchemeType": {
36429
- "declaration": "\"dark\" | \"light\" | \"all\"",
36992
+ "declaration": "\"all\" | \"dark\" | \"light\"",
36430
36993
  "docstring": "",
36431
36994
  "path": "src/type/preference.ts"
36432
36995
  },
@@ -36475,11 +37038,6 @@
36475
37038
  "docstring": "",
36476
37039
  "path": "src/components/mds-push-notification-item/meta/event-detail.ts"
36477
37040
  },
36478
- "src/type/text.ts::TypographyHeadingTagType": {
36479
- "declaration": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\"",
36480
- "docstring": "",
36481
- "path": "src/type/text.ts"
36482
- },
36483
37041
  "src/components/mds-radial-menu/meta/types.ts::Direction": {
36484
37042
  "declaration": "export type Direction = 'clockwise' | 'counterclockwise';",
36485
37043
  "docstring": "",
@@ -36581,7 +37139,7 @@
36581
37139
  "path": "src/components/mds-table-header-cell/meta/event-detail.ts"
36582
37140
  },
36583
37141
  "src/type/text.ts::TypographyTagType": {
36584
- "declaration": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | \"label\" | \"code\" | \"strong\" | \"abbr\" | \"address\" | \"article\" | \"b\" | \"bdo\" | \"blockquote\" | \"cite\" | \"dd\" | \"del\" | \"details\" | \"dfn\" | \"div\" | \"dl\" | \"dt\" | \"em\" | \"figcaption\" | \"i\" | \"ins\" | \"kbd\" | \"legend\" | \"li\" | \"mark\" | \"ol\" | \"p\" | \"pre\" | \"q\" | \"rb\" | \"rt\" | \"ruby\" | \"s\" | \"samp\" | \"small\" | \"span\" | \"sub\" | \"summary\" | \"sup\" | \"time\" | \"u\" | \"ul\" | \"var\"",
37142
+ "declaration": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | \"label\" | \"code\" | \"abbr\" | \"address\" | \"article\" | \"b\" | \"bdo\" | \"blockquote\" | \"cite\" | \"dd\" | \"del\" | \"details\" | \"dfn\" | \"div\" | \"dl\" | \"dt\" | \"em\" | \"figcaption\" | \"i\" | \"ins\" | \"kbd\" | \"legend\" | \"li\" | \"mark\" | \"ol\" | \"p\" | \"pre\" | \"q\" | \"rb\" | \"rt\" | \"ruby\" | \"s\" | \"samp\" | \"small\" | \"span\" | \"strong\" | \"sub\" | \"summary\" | \"sup\" | \"time\" | \"u\" | \"ul\" | \"var\"",
36585
37143
  "docstring": "",
36586
37144
  "path": "src/type/text.ts"
36587
37145
  },
@@ -36641,5 +37199,6 @@
36641
37199
  "path": "src/components/mds-video-wall/meta/types.ts"
36642
37200
  }
36643
37201
  },
36644
- "storybook": "https://magma-design-system.github.io/magma/storybook/"
37202
+ "storybook": "https://magma-design-system.github.io/magma/storybook/",
37203
+ "studio": "https://magma-design-system.github.io/magma/studio/"
36645
37204
  }