@maggioli-design-system/magma 2.7.0 → 2.9.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 (363) hide show
  1. package/AGENTS.md +1 -1
  2. package/CHANGELOG.md +45 -0
  3. package/agents/lint.md +20 -2
  4. package/dist/cjs/loader.cjs.js +1 -1
  5. package/dist/cjs/magma-components.cjs.js +1 -1
  6. package/dist/cjs/mds-banner_3.cjs.entry.js +7 -6
  7. package/dist/cjs/mds-book.cjs.entry.js +53 -5
  8. package/dist/cjs/mds-calendar_2.cjs.entry.js +1 -1
  9. package/dist/cjs/mds-emoji.cjs.entry.js +39 -9
  10. package/dist/cjs/mds-filter.cjs.entry.js +1 -1
  11. package/dist/cjs/mds-input-range.cjs.entry.js +1 -1
  12. package/dist/cjs/mds-modal.cjs.entry.js +1 -1
  13. package/dist/cjs/mds-push-notification-item.cjs.entry.js +17 -4
  14. package/dist/cjs/mds-toast.cjs.entry.js +2 -2
  15. package/dist/collection/components/mds-accordion/AGENTS.md +2 -1
  16. package/dist/collection/components/mds-accordion/documentation.json +4 -2
  17. package/dist/collection/components/mds-accordion-item/AGENTS.md +2 -1
  18. package/dist/collection/components/mds-accordion-item/documentation.json +4 -2
  19. package/dist/collection/components/mds-accordion-timer/AGENTS.md +2 -1
  20. package/dist/collection/components/mds-accordion-timer/documentation.json +4 -2
  21. package/dist/collection/components/mds-accordion-timer-item/AGENTS.md +2 -1
  22. package/dist/collection/components/mds-accordion-timer-item/documentation.json +4 -2
  23. package/dist/collection/components/mds-author/AGENTS.md +2 -1
  24. package/dist/collection/components/mds-author/documentation.json +4 -2
  25. package/dist/collection/components/mds-avatar/AGENTS.md +2 -1
  26. package/dist/collection/components/mds-avatar/documentation.json +4 -2
  27. package/dist/collection/components/mds-avatar-stack/AGENTS.md +2 -1
  28. package/dist/collection/components/mds-avatar-stack/documentation.json +4 -2
  29. package/dist/collection/components/mds-avatar-stack-item/AGENTS.md +2 -1
  30. package/dist/collection/components/mds-avatar-stack-item/documentation.json +4 -2
  31. package/dist/collection/components/mds-badge/AGENTS.md +2 -1
  32. package/dist/collection/components/mds-badge/documentation.json +4 -2
  33. package/dist/collection/components/mds-banner/AGENTS.md +7 -4
  34. package/dist/collection/components/mds-banner/antipattern.md +5 -5
  35. package/dist/collection/components/mds-banner/documentation.json +40 -6
  36. package/dist/collection/components/mds-banner/mds-banner.css +7 -10
  37. package/dist/collection/components/mds-banner/mds-banner.js +30 -7
  38. package/dist/collection/components/mds-banner/pattern.md +4 -4
  39. package/dist/collection/components/mds-benchmark-bar/AGENTS.md +2 -1
  40. package/dist/collection/components/mds-benchmark-bar/documentation.json +4 -2
  41. package/dist/collection/components/mds-bibliography/AGENTS.md +2 -1
  42. package/dist/collection/components/mds-bibliography/documentation.json +4 -2
  43. package/dist/collection/components/mds-book/AGENTS.md +9 -4
  44. package/dist/collection/components/mds-book/documentation.json +46 -6
  45. package/dist/collection/components/mds-book/mds-book.css +91 -7
  46. package/dist/collection/components/mds-book/mds-book.js +79 -7
  47. package/dist/collection/components/mds-book/pattern.md +14 -0
  48. package/dist/collection/components/mds-breadcrumb/AGENTS.md +2 -1
  49. package/dist/collection/components/mds-breadcrumb/documentation.json +4 -2
  50. package/dist/collection/components/mds-breadcrumb-item/AGENTS.md +2 -1
  51. package/dist/collection/components/mds-breadcrumb-item/documentation.json +4 -2
  52. package/dist/collection/components/mds-button/AGENTS.md +2 -1
  53. package/dist/collection/components/mds-button/documentation.json +4 -2
  54. package/dist/collection/components/mds-button-dropdown/AGENTS.md +2 -1
  55. package/dist/collection/components/mds-button-dropdown/documentation.json +4 -2
  56. package/dist/collection/components/mds-button-group/AGENTS.md +2 -1
  57. package/dist/collection/components/mds-button-group/documentation.json +4 -2
  58. package/dist/collection/components/mds-calendar/AGENTS.md +2 -1
  59. package/dist/collection/components/mds-calendar/documentation.json +4 -2
  60. package/dist/collection/components/mds-calendar-cell/AGENTS.md +2 -1
  61. package/dist/collection/components/mds-calendar-cell/documentation.json +4 -2
  62. package/dist/collection/components/mds-calendar-cell/mds-calendar-cell.css +4 -1
  63. package/dist/collection/components/mds-card/AGENTS.md +2 -1
  64. package/dist/collection/components/mds-card/documentation.json +4 -2
  65. package/dist/collection/components/mds-card-content/AGENTS.md +2 -1
  66. package/dist/collection/components/mds-card-content/documentation.json +4 -2
  67. package/dist/collection/components/mds-card-footer/AGENTS.md +2 -1
  68. package/dist/collection/components/mds-card-footer/documentation.json +4 -2
  69. package/dist/collection/components/mds-card-header/AGENTS.md +2 -1
  70. package/dist/collection/components/mds-card-header/documentation.json +4 -2
  71. package/dist/collection/components/mds-card-media/AGENTS.md +2 -1
  72. package/dist/collection/components/mds-card-media/documentation.json +4 -2
  73. package/dist/collection/components/mds-chip/AGENTS.md +2 -1
  74. package/dist/collection/components/mds-chip/documentation.json +4 -2
  75. package/dist/collection/components/mds-details/AGENTS.md +2 -1
  76. package/dist/collection/components/mds-details/documentation.json +4 -2
  77. package/dist/collection/components/mds-dropdown/AGENTS.md +2 -1
  78. package/dist/collection/components/mds-dropdown/documentation.json +4 -2
  79. package/dist/collection/components/mds-emoji/AGENTS.md +2 -1
  80. package/dist/collection/components/mds-emoji/asset/simi.svg +1 -1
  81. package/dist/collection/components/mds-emoji/documentation.json +4 -2
  82. package/dist/collection/components/mds-emoji/mds-emoji.js +38 -8
  83. package/dist/collection/components/mds-entity/AGENTS.md +2 -1
  84. package/dist/collection/components/mds-entity/documentation.json +4 -2
  85. package/dist/collection/components/mds-file/AGENTS.md +2 -1
  86. package/dist/collection/components/mds-file/documentation.json +4 -2
  87. package/dist/collection/components/mds-file-preview/AGENTS.md +2 -1
  88. package/dist/collection/components/mds-file-preview/documentation.json +4 -2
  89. package/dist/collection/components/mds-filter/AGENTS.md +3 -2
  90. package/dist/collection/components/mds-filter/documentation.json +10 -2
  91. package/dist/collection/components/mds-filter/mds-filter.css +5 -1
  92. package/dist/collection/components/mds-filter-item/AGENTS.md +2 -1
  93. package/dist/collection/components/mds-filter-item/documentation.json +4 -2
  94. package/dist/collection/components/mds-header/AGENTS.md +2 -1
  95. package/dist/collection/components/mds-header/documentation.json +5 -3
  96. package/dist/collection/components/mds-header/pattern.md +3 -3
  97. package/dist/collection/components/mds-header-bar/AGENTS.md +2 -1
  98. package/dist/collection/components/mds-header-bar/documentation.json +4 -2
  99. package/dist/collection/components/mds-help/AGENTS.md +2 -1
  100. package/dist/collection/components/mds-help/documentation.json +4 -2
  101. package/dist/collection/components/mds-horizontal-scroll/AGENTS.md +2 -1
  102. package/dist/collection/components/mds-horizontal-scroll/documentation.json +4 -2
  103. package/dist/collection/components/mds-hr/AGENTS.md +2 -1
  104. package/dist/collection/components/mds-hr/documentation.json +4 -2
  105. package/dist/collection/components/mds-icon/AGENTS.md +2 -1
  106. package/dist/collection/components/mds-icon/documentation.json +4 -2
  107. package/dist/collection/components/mds-img/AGENTS.md +2 -1
  108. package/dist/collection/components/mds-img/documentation.json +4 -2
  109. package/dist/collection/components/mds-input/AGENTS.md +2 -1
  110. package/dist/collection/components/mds-input/documentation.json +4 -2
  111. package/dist/collection/components/mds-input-date/AGENTS.md +2 -1
  112. package/dist/collection/components/mds-input-date/documentation.json +4 -2
  113. package/dist/collection/components/mds-input-date-range/AGENTS.md +2 -1
  114. package/dist/collection/components/mds-input-date-range/documentation.json +4 -2
  115. package/dist/collection/components/mds-input-date-range-preselection/AGENTS.md +2 -1
  116. package/dist/collection/components/mds-input-date-range-preselection/documentation.json +4 -2
  117. package/dist/collection/components/mds-input-field/AGENTS.md +2 -1
  118. package/dist/collection/components/mds-input-field/documentation.json +4 -2
  119. package/dist/collection/components/mds-input-otp/AGENTS.md +2 -1
  120. package/dist/collection/components/mds-input-otp/documentation.json +5 -3
  121. package/dist/collection/components/mds-input-otp/pattern.md +1 -1
  122. package/dist/collection/components/mds-input-range/AGENTS.md +2 -1
  123. package/dist/collection/components/mds-input-range/documentation.json +4 -2
  124. package/dist/collection/components/mds-input-range/mds-input-range.css +7 -5
  125. package/dist/collection/components/mds-input-select/AGENTS.md +2 -1
  126. package/dist/collection/components/mds-input-select/documentation.json +4 -2
  127. package/dist/collection/components/mds-input-switch/AGENTS.md +2 -1
  128. package/dist/collection/components/mds-input-switch/documentation.json +4 -2
  129. package/dist/collection/components/mds-input-tip/AGENTS.md +2 -1
  130. package/dist/collection/components/mds-input-tip/documentation.json +4 -2
  131. package/dist/collection/components/mds-input-tip-item/AGENTS.md +2 -1
  132. package/dist/collection/components/mds-input-tip-item/documentation.json +4 -2
  133. package/dist/collection/components/mds-input-upload/AGENTS.md +2 -1
  134. package/dist/collection/components/mds-input-upload/documentation.json +4 -2
  135. package/dist/collection/components/mds-keyboard/AGENTS.md +2 -1
  136. package/dist/collection/components/mds-keyboard/documentation.json +4 -2
  137. package/dist/collection/components/mds-keyboard-key/AGENTS.md +2 -1
  138. package/dist/collection/components/mds-keyboard-key/documentation.json +4 -2
  139. package/dist/collection/components/mds-kpi/AGENTS.md +2 -1
  140. package/dist/collection/components/mds-kpi/documentation.json +4 -2
  141. package/dist/collection/components/mds-kpi-item/AGENTS.md +2 -1
  142. package/dist/collection/components/mds-kpi-item/documentation.json +4 -2
  143. package/dist/collection/components/mds-label/AGENTS.md +2 -1
  144. package/dist/collection/components/mds-label/documentation.json +4 -2
  145. package/dist/collection/components/mds-link/AGENTS.md +2 -1
  146. package/dist/collection/components/mds-link/documentation.json +4 -2
  147. package/dist/collection/components/mds-list/AGENTS.md +2 -1
  148. package/dist/collection/components/mds-list/documentation.json +4 -2
  149. package/dist/collection/components/mds-list-item/AGENTS.md +2 -1
  150. package/dist/collection/components/mds-list-item/documentation.json +4 -2
  151. package/dist/collection/components/mds-mention/AGENTS.md +2 -1
  152. package/dist/collection/components/mds-mention/documentation.json +4 -2
  153. package/dist/collection/components/mds-modal/AGENTS.md +5 -1
  154. package/dist/collection/components/mds-modal/documentation.json +5 -3
  155. package/dist/collection/components/mds-modal/mds-modal.css +136 -3
  156. package/dist/collection/components/mds-note/AGENTS.md +2 -1
  157. package/dist/collection/components/mds-note/documentation.json +4 -2
  158. package/dist/collection/components/mds-notification/AGENTS.md +2 -1
  159. package/dist/collection/components/mds-notification/documentation.json +4 -2
  160. package/dist/collection/components/mds-paginator/AGENTS.md +2 -1
  161. package/dist/collection/components/mds-paginator/documentation.json +4 -2
  162. package/dist/collection/components/mds-paginator-item/AGENTS.md +2 -1
  163. package/dist/collection/components/mds-paginator-item/documentation.json +4 -2
  164. package/dist/collection/components/mds-policy-ai/AGENTS.md +2 -1
  165. package/dist/collection/components/mds-policy-ai/documentation.json +4 -2
  166. package/dist/collection/components/mds-pref/AGENTS.md +2 -1
  167. package/dist/collection/components/mds-pref/documentation.json +4 -2
  168. package/dist/collection/components/mds-pref-animation/AGENTS.md +2 -1
  169. package/dist/collection/components/mds-pref-animation/documentation.json +4 -2
  170. package/dist/collection/components/mds-pref-consumption/AGENTS.md +2 -1
  171. package/dist/collection/components/mds-pref-consumption/documentation.json +4 -2
  172. package/dist/collection/components/mds-pref-contrast/AGENTS.md +2 -1
  173. package/dist/collection/components/mds-pref-contrast/documentation.json +4 -2
  174. package/dist/collection/components/mds-pref-language/AGENTS.md +2 -1
  175. package/dist/collection/components/mds-pref-language/documentation.json +4 -2
  176. package/dist/collection/components/mds-pref-language-item/AGENTS.md +2 -1
  177. package/dist/collection/components/mds-pref-language-item/documentation.json +4 -2
  178. package/dist/collection/components/mds-pref-mode/AGENTS.md +2 -1
  179. package/dist/collection/components/mds-pref-mode/documentation.json +4 -2
  180. package/dist/collection/components/mds-pref-theme/AGENTS.md +2 -1
  181. package/dist/collection/components/mds-pref-theme/documentation.json +4 -2
  182. package/dist/collection/components/mds-pref-theme-item/AGENTS.md +2 -1
  183. package/dist/collection/components/mds-pref-theme-item/documentation.json +4 -2
  184. package/dist/collection/components/mds-price-table/AGENTS.md +2 -1
  185. package/dist/collection/components/mds-price-table/documentation.json +4 -2
  186. package/dist/collection/components/mds-price-table-features/AGENTS.md +2 -1
  187. package/dist/collection/components/mds-price-table-features/documentation.json +4 -2
  188. package/dist/collection/components/mds-price-table-features-cell/AGENTS.md +2 -1
  189. package/dist/collection/components/mds-price-table-features-cell/documentation.json +4 -2
  190. package/dist/collection/components/mds-price-table-features-row/AGENTS.md +2 -1
  191. package/dist/collection/components/mds-price-table-features-row/documentation.json +4 -2
  192. package/dist/collection/components/mds-price-table-header/AGENTS.md +2 -1
  193. package/dist/collection/components/mds-price-table-header/documentation.json +4 -2
  194. package/dist/collection/components/mds-price-table-list/AGENTS.md +2 -1
  195. package/dist/collection/components/mds-price-table-list/documentation.json +4 -2
  196. package/dist/collection/components/mds-price-table-list-item/AGENTS.md +2 -1
  197. package/dist/collection/components/mds-price-table-list-item/documentation.json +4 -2
  198. package/dist/collection/components/mds-progress/AGENTS.md +2 -1
  199. package/dist/collection/components/mds-progress/documentation.json +4 -2
  200. package/dist/collection/components/mds-push-notification/AGENTS.md +3 -2
  201. package/dist/collection/components/mds-push-notification/documentation.json +6 -4
  202. package/dist/collection/components/mds-push-notification/pattern.md +2 -2
  203. package/dist/collection/components/mds-push-notification-item/AGENTS.md +6 -3
  204. package/dist/collection/components/mds-push-notification-item/documentation.json +38 -5
  205. package/dist/collection/components/mds-push-notification-item/mds-push-notification-item.css +1 -0
  206. package/dist/collection/components/mds-push-notification-item/mds-push-notification-item.js +40 -5
  207. package/dist/collection/components/mds-push-notification-item/pattern.md +3 -3
  208. package/dist/collection/components/mds-quote/AGENTS.md +2 -1
  209. package/dist/collection/components/mds-quote/documentation.json +4 -2
  210. package/dist/collection/components/mds-radial-menu/AGENTS.md +2 -1
  211. package/dist/collection/components/mds-radial-menu/documentation.json +4 -2
  212. package/dist/collection/components/mds-radial-menu-item/AGENTS.md +2 -1
  213. package/dist/collection/components/mds-radial-menu-item/documentation.json +4 -2
  214. package/dist/collection/components/mds-radial-progress/AGENTS.md +2 -1
  215. package/dist/collection/components/mds-radial-progress/documentation.json +4 -2
  216. package/dist/collection/components/mds-separator/AGENTS.md +2 -1
  217. package/dist/collection/components/mds-separator/documentation.json +4 -2
  218. package/dist/collection/components/mds-spinner/AGENTS.md +2 -1
  219. package/dist/collection/components/mds-spinner/documentation.json +5 -3
  220. package/dist/collection/components/mds-spinner/pattern.md +9 -6
  221. package/dist/collection/components/mds-status-bar/AGENTS.md +2 -1
  222. package/dist/collection/components/mds-status-bar/documentation.json +4 -2
  223. package/dist/collection/components/mds-stepper-bar/AGENTS.md +2 -1
  224. package/dist/collection/components/mds-stepper-bar/documentation.json +4 -2
  225. package/dist/collection/components/mds-stepper-bar-item/AGENTS.md +2 -1
  226. package/dist/collection/components/mds-stepper-bar-item/documentation.json +4 -2
  227. package/dist/collection/components/mds-tab/AGENTS.md +2 -1
  228. package/dist/collection/components/mds-tab/documentation.json +4 -2
  229. package/dist/collection/components/mds-tab-bar/AGENTS.md +2 -1
  230. package/dist/collection/components/mds-tab-bar/documentation.json +4 -2
  231. package/dist/collection/components/mds-tab-bar-item/AGENTS.md +2 -1
  232. package/dist/collection/components/mds-tab-bar-item/documentation.json +4 -2
  233. package/dist/collection/components/mds-tab-item/AGENTS.md +2 -1
  234. package/dist/collection/components/mds-tab-item/documentation.json +4 -2
  235. package/dist/collection/components/mds-table/AGENTS.md +2 -1
  236. package/dist/collection/components/mds-table/documentation.json +4 -2
  237. package/dist/collection/components/mds-table-body/AGENTS.md +2 -1
  238. package/dist/collection/components/mds-table-body/documentation.json +4 -2
  239. package/dist/collection/components/mds-table-cell/AGENTS.md +2 -1
  240. package/dist/collection/components/mds-table-cell/documentation.json +4 -2
  241. package/dist/collection/components/mds-table-footer/AGENTS.md +2 -1
  242. package/dist/collection/components/mds-table-footer/documentation.json +4 -2
  243. package/dist/collection/components/mds-table-header/AGENTS.md +2 -1
  244. package/dist/collection/components/mds-table-header/documentation.json +4 -2
  245. package/dist/collection/components/mds-table-header-cell/AGENTS.md +2 -1
  246. package/dist/collection/components/mds-table-header-cell/documentation.json +4 -2
  247. package/dist/collection/components/mds-table-row/AGENTS.md +7 -2
  248. package/dist/collection/components/mds-table-row/documentation.json +11 -3
  249. package/dist/collection/components/mds-table-row/mds-table-row.css +1 -0
  250. package/dist/collection/components/mds-table-row/pattern.md +14 -1
  251. package/dist/collection/components/mds-text/AGENTS.md +2 -1
  252. package/dist/collection/components/mds-text/documentation.json +4 -2
  253. package/dist/collection/components/mds-toast/AGENTS.md +8 -5
  254. package/dist/collection/components/mds-toast/antipattern.md +2 -2
  255. package/dist/collection/components/mds-toast/documentation.json +40 -6
  256. package/dist/collection/components/mds-toast/mds-toast.js +26 -4
  257. package/dist/collection/components/mds-toast/pattern.md +2 -2
  258. package/dist/collection/components/mds-toast-region/AGENTS.md +2 -1
  259. package/dist/collection/components/mds-toast-region/documentation.json +5 -3
  260. package/dist/collection/components/mds-toast-region/pattern.md +10 -2
  261. package/dist/collection/components/mds-tooltip/AGENTS.md +2 -1
  262. package/dist/collection/components/mds-tooltip/documentation.json +4 -2
  263. package/dist/collection/components/mds-tree/AGENTS.md +3 -2
  264. package/dist/collection/components/mds-tree/documentation.json +5 -3
  265. package/dist/collection/components/mds-tree/pattern.md +13 -13
  266. package/dist/collection/components/mds-tree-item/AGENTS.md +2 -1
  267. package/dist/collection/components/mds-tree-item/documentation.json +4 -2
  268. package/dist/collection/components/mds-url-view/AGENTS.md +2 -1
  269. package/dist/collection/components/mds-url-view/documentation.json +4 -2
  270. package/dist/collection/components/mds-usage/AGENTS.md +2 -1
  271. package/dist/collection/components/mds-usage/documentation.json +4 -2
  272. package/dist/collection/components/mds-video-wall/AGENTS.md +2 -1
  273. package/dist/collection/components/mds-video-wall/documentation.json +4 -2
  274. package/dist/collection/components/mds-zero/AGENTS.md +2 -1
  275. package/dist/collection/components/mds-zero/documentation.json +4 -2
  276. package/dist/components/mds-banner.js +1 -1
  277. package/dist/components/mds-book.js +1 -1
  278. package/dist/components/mds-calendar-cell.js +1 -1
  279. package/dist/components/mds-calendar.js +1 -1
  280. package/dist/components/mds-emoji.js +1 -1
  281. package/dist/components/mds-filter.js +1 -1
  282. package/dist/components/mds-header.js +1 -1
  283. package/dist/components/mds-input-date-range.js +1 -1
  284. package/dist/components/mds-input-date.js +1 -1
  285. package/dist/components/mds-input-range.js +1 -1
  286. package/dist/components/mds-modal.js +1 -1
  287. package/dist/components/mds-policy-ai.js +1 -1
  288. package/dist/components/mds-push-notification-item.js +1 -1
  289. package/dist/components/mds-status-bar.js +1 -1
  290. package/dist/components/mds-toast.js +1 -1
  291. package/dist/components/p-BeZGLnJJ.js +1 -0
  292. package/dist/components/p-Chk4rI7N.js +1 -0
  293. package/dist/components/{p-CNpL55c-.js → p-Cwg4vtOr.js} +1 -1
  294. package/dist/components/p-Dzkiu-es.js +1 -0
  295. package/dist/documentation.json +406 -143
  296. package/dist/esm/loader.js +1 -1
  297. package/dist/esm/magma-components.js +1 -1
  298. package/dist/esm/mds-banner_3.entry.js +7 -6
  299. package/dist/esm/mds-book.entry.js +53 -5
  300. package/dist/esm/mds-calendar_2.entry.js +1 -1
  301. package/dist/esm/mds-emoji.entry.js +39 -9
  302. package/dist/esm/mds-filter.entry.js +1 -1
  303. package/dist/esm/mds-input-range.entry.js +1 -1
  304. package/dist/esm/mds-modal.entry.js +1 -1
  305. package/dist/esm/mds-push-notification-item.entry.js +17 -4
  306. package/dist/esm/mds-toast.entry.js +2 -2
  307. package/dist/esm-es5/loader.js +1 -1
  308. package/dist/esm-es5/magma-components.js +1 -1
  309. package/dist/esm-es5/mds-banner_3.entry.js +2 -2
  310. package/dist/esm-es5/mds-book.entry.js +33 -26
  311. package/dist/esm-es5/mds-calendar_2.entry.js +8 -8
  312. package/dist/esm-es5/mds-emoji.entry.js +40 -31
  313. package/dist/esm-es5/mds-filter.entry.js +1 -1
  314. package/dist/esm-es5/mds-input-range.entry.js +7 -7
  315. package/dist/esm-es5/mds-modal.entry.js +15 -15
  316. package/dist/esm-es5/mds-push-notification-item.entry.js +7 -3
  317. package/dist/esm-es5/mds-toast.entry.js +2 -2
  318. package/dist/hydrate/index.js +130 -32
  319. package/dist/hydrate/index.mjs +130 -32
  320. package/dist/lint/core/checks.d.ts +5 -0
  321. package/dist/lint/core/checks.js +17 -0
  322. package/dist/lint/core/data.d.ts +4 -1
  323. package/dist/lint/core/data.js +3 -1
  324. package/dist/lint/eslint/index.js +6 -4
  325. package/dist/magma-components/magma-components.esm.js +1 -1
  326. package/dist/magma-components/{p-354a5b47.entry.js → p-02b106c2.entry.js} +1 -1
  327. package/dist/magma-components/{p-17ccfc01.system.entry.js → p-3bc65166.system.entry.js} +55 -48
  328. package/dist/magma-components/p-425ca155.entry.js +1 -0
  329. package/dist/magma-components/p-523f0c30.system.entry.js +80 -0
  330. package/dist/magma-components/{p-07d35da6.entry.js → p-5306606b.entry.js} +1 -1
  331. package/dist/magma-components/{p-1b67b149.system.entry.js → p-798f460b.system.entry.js} +1 -1
  332. package/dist/magma-components/{p-e5f893f9.system.entry.js → p-7db14777.system.entry.js} +1 -1
  333. package/dist/magma-components/{p-e8452cce.entry.js → p-8641b7b2.entry.js} +1 -1
  334. package/dist/magma-components/{p-3a7c4314.system.entry.js → p-95ccf46d.system.entry.js} +4 -4
  335. package/dist/magma-components/p-968a2237.entry.js +1 -0
  336. package/dist/magma-components/p-9dd9eadd.entry.js +1 -0
  337. package/dist/magma-components/p-B8zYiZQY.system.js +1 -1
  338. package/dist/magma-components/{p-160cd923.entry.js → p-a25327a1.entry.js} +1 -1
  339. package/dist/magma-components/p-a67381bf.entry.js +1 -0
  340. package/dist/magma-components/{p-c2c693ed.system.entry.js → p-b27cb1ac.system.entry.js} +14 -5
  341. package/dist/magma-components/{p-6df26141.system.entry.js → p-c0286dc3.system.entry.js} +1 -1
  342. package/dist/magma-components/p-c89060ec.system.entry.js +41 -0
  343. package/dist/magma-components/p-eb12be86.system.entry.js +24 -0
  344. package/dist/magma-components/p-ebeb3fff.entry.js +1 -0
  345. package/dist/stats.json +383 -139
  346. package/dist/types/components/mds-banner/mds-banner.d.ts +9 -2
  347. package/dist/types/components/mds-book/mds-book.d.ts +19 -2
  348. package/dist/types/components/mds-emoji/mds-emoji.d.ts +1 -0
  349. package/dist/types/components/mds-push-notification-item/mds-push-notification-item.d.ts +10 -1
  350. package/dist/types/components/mds-toast/mds-toast.d.ts +7 -1
  351. package/dist/types/components.d.ts +56 -12
  352. package/package.json +8 -8
  353. package/dist/components/p-B8hgyXdE.js +0 -1
  354. package/dist/components/p-CYK2Xr_v.js +0 -1
  355. package/dist/components/p-DbVGGhs_.js +0 -1
  356. package/dist/magma-components/p-14b13850.entry.js +0 -1
  357. package/dist/magma-components/p-386bb24e.system.entry.js +0 -41
  358. package/dist/magma-components/p-6d96d223.entry.js +0 -1
  359. package/dist/magma-components/p-79fd07e7.system.entry.js +0 -80
  360. package/dist/magma-components/p-7e7391fd.entry.js +0 -1
  361. package/dist/magma-components/p-df387755.entry.js +0 -1
  362. package/dist/magma-components/p-ee780f82.system.entry.js +0 -20
  363. package/dist/magma-components/p-f2211b1f.entry.js +0 -1
@@ -1,5 +1,5 @@
1
1
  {
2
- "timestamp": "2026-10-24T18:39:37",
2
+ "timestamp": "2026-10-27T10:28:31",
3
3
  "compiler": {
4
4
  "name": "@stencil/core",
5
5
  "version": "4.45.2",
@@ -183,7 +183,8 @@
183
183
  "states": [],
184
184
  "dependents": [],
185
185
  "dependencies": [],
186
- "dependencyGraph": {}
186
+ "dependencyGraph": {},
187
+ "storybook": "ui-accordion--docs"
187
188
  },
188
189
  {
189
190
  "filePath": "src/components/mds-accordion-item/mds-accordion-item.tsx",
@@ -473,7 +474,8 @@
473
474
  "mds-accordion-item": [
474
475
  "mds-text"
475
476
  ]
476
- }
477
+ },
478
+ "storybook": "ui-accordion-accordion-item--docs"
477
479
  },
478
480
  {
479
481
  "filePath": "src/components/mds-accordion-timer/mds-accordion-timer.tsx",
@@ -641,7 +643,8 @@
641
643
  "states": [],
642
644
  "dependents": [],
643
645
  "dependencies": [],
644
- "dependencyGraph": {}
646
+ "dependencyGraph": {},
647
+ "storybook": "ui-accordion-timer--docs"
645
648
  },
646
649
  {
647
650
  "filePath": "src/components/mds-accordion-timer-item/mds-accordion-timer-item.tsx",
@@ -1041,7 +1044,8 @@
1041
1044
  "mds-icon",
1042
1045
  "mds-text"
1043
1046
  ]
1044
- }
1047
+ },
1048
+ "storybook": "ui-accordion-timer-accordion-timer-item--docs"
1045
1049
  },
1046
1050
  {
1047
1051
  "filePath": "src/components/mds-author/mds-author.tsx",
@@ -1087,7 +1091,8 @@
1087
1091
  "states": [],
1088
1092
  "dependents": [],
1089
1093
  "dependencies": [],
1090
- "dependencyGraph": {}
1094
+ "dependencyGraph": {},
1095
+ "storybook": "ui-author--docs"
1091
1096
  },
1092
1097
  {
1093
1098
  "filePath": "src/components/mds-avatar/mds-avatar.tsx",
@@ -1449,7 +1454,8 @@
1449
1454
  "mds-push-notification-item": [
1450
1455
  "mds-avatar"
1451
1456
  ]
1452
- }
1457
+ },
1458
+ "storybook": "ui-avatar--docs"
1453
1459
  },
1454
1460
  {
1455
1461
  "filePath": "src/components/mds-avatar-stack/mds-avatar-stack.tsx",
@@ -1652,7 +1658,8 @@
1652
1658
  "mds-icon",
1653
1659
  "mds-text"
1654
1660
  ]
1655
- }
1661
+ },
1662
+ "storybook": "ui-avatar-stack--docs"
1656
1663
  },
1657
1664
  {
1658
1665
  "filePath": "src/components/mds-avatar-stack-item/mds-avatar-stack-item.tsx",
@@ -1970,7 +1977,8 @@
1970
1977
  "mds-avatar-stack": [
1971
1978
  "mds-avatar-stack-item"
1972
1979
  ]
1973
- }
1980
+ },
1981
+ "storybook": "ui-avatar-stack-item--docs"
1974
1982
  },
1975
1983
  {
1976
1984
  "filePath": "src/components/mds-badge/mds-badge.tsx",
@@ -2286,7 +2294,8 @@
2286
2294
  "mds-table": [
2287
2295
  "mds-badge"
2288
2296
  ]
2289
- }
2297
+ },
2298
+ "storybook": "ui-badge--docs"
2290
2299
  },
2291
2300
  {
2292
2301
  "filePath": "src/components/mds-banner/mds-banner.tsx",
@@ -2313,9 +2322,9 @@
2313
2322
  }
2314
2323
  ],
2315
2324
  "usage": {
2316
- "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 `deletable` 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#### 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- **`deletable`** opts the banner into being dismissible - choose it for transient or user-acknowledged messages rather than persistent context.\n- The **default slot** carries the body text/markup; the **`action` slot** holds inline controls, with `mds-button` the recommended element.\n",
2317
- "2. Pattern": "Correct and idiomatic ways to use the `<mds-banner>` component, ordered from most common to most specialized. Patterns 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 `deletable` 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\" deletable 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 `deletable` 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\" deletable 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",
2318
- "3. Antipattern": "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/anti-patterns.md`](../../../../agents/anti-patterns.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 `deletable=\"false\"` to Hide the Close Button\n\n`deletable` is a boolean prop, and a false boolean is an absent attribute ([`agents/anti-patterns.md`](../../../../agents/anti-patterns.md)). Stencil reads the string `\"false\"` as `false` here, so the button is hidden, but the attribute stays on the element and any `[deletable]` selector still matches it. Remove the attribute (or omit it) to hide the button.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"error\" deletable=\"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\" deletable 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\" deletable 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"
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#### 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. Pattern": "Correct and idiomatic ways to use the `<mds-banner>` component, ordered from most common to most specialized. Patterns 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. Antipattern": "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/anti-patterns.md`](../../../../agents/anti-patterns.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/anti-patterns.md`](../../../../agents/anti-patterns.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"
2319
2328
  },
2320
2329
  "props": [
2321
2330
  {
@@ -2329,7 +2338,39 @@
2329
2338
  "mutable": false,
2330
2339
  "attr": "deletable",
2331
2340
  "reflectToAttr": false,
2332
- "docs": "Shows the cross icon to perform cancel/delete action on element",
2341
+ "docs": "Shows the close button, as `dismissible` does.",
2342
+ "docsTags": [
2343
+ {
2344
+ "name": "deprecated",
2345
+ "text": "Use `dismissible`: the button dismisses the message, it deletes nothing.\nGoes in the next major."
2346
+ }
2347
+ ],
2348
+ "deprecation": "Use `dismissible`: the button dismisses the message, it deletes nothing.\nGoes in the next major.",
2349
+ "values": [
2350
+ {
2351
+ "type": "boolean"
2352
+ },
2353
+ {
2354
+ "type": "undefined"
2355
+ }
2356
+ ],
2357
+ "optional": true,
2358
+ "required": false,
2359
+ "getter": false,
2360
+ "setter": false
2361
+ },
2362
+ {
2363
+ "name": "dismissible",
2364
+ "type": "boolean | undefined",
2365
+ "complexType": {
2366
+ "original": "boolean",
2367
+ "resolved": "boolean | undefined",
2368
+ "references": {}
2369
+ },
2370
+ "mutable": false,
2371
+ "attr": "dismissible",
2372
+ "reflectToAttr": false,
2373
+ "docs": "Shows a close button that dismisses the banner: activating it emits `mdsBannerClose`",
2333
2374
  "docsTags": [],
2334
2375
  "values": [
2335
2376
  {
@@ -2670,7 +2711,8 @@
2670
2711
  "mds-policy-ai": [
2671
2712
  "mds-banner"
2672
2713
  ]
2673
- }
2714
+ },
2715
+ "storybook": "ui-banner--docs"
2674
2716
  },
2675
2717
  {
2676
2718
  "filePath": "src/components/mds-benchmark-bar/mds-benchmark-bar.tsx",
@@ -2978,7 +3020,8 @@
2978
3020
  "mds-icon",
2979
3021
  "mds-text"
2980
3022
  ]
2981
- }
3023
+ },
3024
+ "storybook": "ui-benchmark-bar--docs"
2982
3025
  },
2983
3026
  {
2984
3027
  "filePath": "src/components/mds-bibliography/mds-bibliography.tsx",
@@ -3393,7 +3436,8 @@
3393
3436
  "mds-bibliography": [
3394
3437
  "mds-text"
3395
3438
  ]
3396
- }
3439
+ },
3440
+ "storybook": "ui-bibliography--docs"
3397
3441
  },
3398
3442
  {
3399
3443
  "filePath": "src/components/mds-book/mds-book.tsx",
@@ -3412,8 +3456,8 @@
3412
3456
  }
3413
3457
  ],
3414
3458
  "usage": {
3415
- "1. Description": "The `<mds-book>` web component shows a book as a physical object, from the image of its front cover alone: front cover, spine and page block drawn in CSS 3D, turned a little so the spine shows. It is the catalogue and product-page counterpart of `<mds-img>`, for publications rather than pictures.\n\n#### Semantic Behavior\n\n- **One image of the book**: The host is a single `role=\"img\"` named by `alt`, or by `name` and `author` (\"Title by Author\", localised in el/en/es/it), or by a generic \"Book\" when there is neither. An empty `alt` marks the book as decorative (`role=\"presentation\"`). The text printed on the spine and on a drawn cover is hidden from assistive technologies, since it repeats that name.\n- **The sides come from the cover**: The spine continues the left edge of the cover image and the board edges its top and right edges, as a wraparound cover prints its design on, so no spine or back cover image is needed. Without an image they take `--mds-book-color`.\n- **A drawn cover instead of a broken image**: Without `src`, or when the image fails to load, the front shows the title, the author and the publisher on `--mds-book-color`. A new `src` tries again.\n- **A neutral shape while loading**: Until its image arrives, a book with `src` is drawn in a neutral surface colour, so a lazy catalogue does not flash in the colour of drawn covers.\n- **Light and shadow**: The book is seen a little from above. Each face takes the light by how it turns toward it, in a light touch that shows the volume without drawing the eye. Its shadow falls on the surface it rests on, under its tail when it stands and under its back cover when it lies, darkest where it touches and soon gone; around its outline only a halo faint enough to part a light cover from a light page.\n- **Movement**: The book rests in its `pose`. On hover it rises off the surface, its shadow fading there, and leans a little toward the pointer, with a faint sheen on the cover. A drag (mouse, pen or finger) turns it further, within limits, to show the spine or the pages, never the back, or spins a lying book on its surface; it settles back when released, or when the pointer leaves the window or the frame of the page, where its release could not reach the book. A vertical swipe still scrolls the page.\n- **Not a control**: The book has no action of its own. To make it a link, wrap it: the click that ends a drag does not follow the link, a plain click does.\n- **Reduced motion**: With the animation preference set to reduce (or the system asking for it, when there is no controller), the book keeps its resting pose: no lean, no lift, no drag.\n- **Consumption**: The consumption preference sets how much the book costs to draw. At `high` (the default, and on a page without the controller) it does everything; at `medium` it moves without the sheen and without the halo, a filter computed again on every frame; at `low` it is drawn once, in its pose, and never animated. While it moves, only opacities and transforms change, which the compositor applies without painting the faces again.\n\n#### Properties & Visual Configurations\n\n- **`pose`**: how the book is shown, after the usual shots of product photography. A drag turns it from there, and it goes back to it when released.\n - `'spine'`: standing, turned to show its spine; the default, and the one for a catalogue.\n - `'fore-edge'`: standing, turned the other way to show its pages.\n - `'front'`: facing the reader, flat, the cover as it is; the light still shows the binding when it moves.\n - `'lying'`: lying on its back, seen from above, its tail toward the reader: a book on a desk.\n - `'lying-turned'`: lying, spun on the surface to show its spine and its tail.\n\n- **`format`**: the proportions of the book, in one field that also carries the orientation.\n - `'auto'`: the proportions of the image, read once it has loaded (a square cover gives a square book); before that, and without an image, 17x24. Pick it when the image already has the true proportions.\n - `'a4'`, `'a5'`, `'b5'`: the ISO formats, portrait. Any other format is `WxH` in centimetres, the order of the two numbers being the orientation: `'17x24'` portrait, `'24x17'` landscape, `'21x21'` square. A fixed format keeps its shape before the image loads and crops small differences of the image.\n- **`pages`**: the number of pages, from the catalogue record, which sets how deep the book is against the width of its format (17 cm for `'auto'`). A short book is printed on bulky paper and a long volume on thin paper, so a page goes from 0.1 mm at 1 page to 0.05 mm at 1000 pages and beyond, in proportion: 64 pages make 6 mm, 300 pages 2.5 cm, 1000 pages 5 cm, and an A4 of the same pages looks thinner than a 17x24. A spine under 5 mm carries no text.\n- **`binding`**: how the book is built, which shows on its head, its fore edge and its spine.\n - `'paperback'`: cut flush, the cover a hairline on the same edge as the pages, a flat spine.\n - `'hardcover'`: rigid boards about 2.5 mm thick, overhanging a page block set in from them by about 3 mm, the endpapers showing in the gap, a headband, a rounded spine and a hinge groove on the front.\n- **`name`**, **`author`**, **`publisher`**: the same names as on `<mds-bibliography>`, so one catalogue record feeds both.\n- **Size**: the book is sized as an image is, in the proportions of its format: give it a width, and its height follows; give it a height, and its width follows. With neither, it fills the width of its container, as a block does; where nothing gives it a width (a row of a flex layout) it is 200 px wide. Its box is the front cover at rest: the turned book reaches a little beyond it, by a few percent of its width on each side standing, by up to a third lying spun round, so leave it some room inside a container that clips.\n",
3416
- "2. Pattern": "Correct and idiomatic ways to use the `<mds-book>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### A Book from Its Cover\n\nThe canonical form: the cover image and the catalogue data. The title and the author name the book for assistive technologies and are printed on the spine.\n\n```html\n<mds-book\n src=\"/covers/operazioni-straordinarie.webp\"\n name=\"Operazioni straordinarie\"\n author=\"Antonio D'Amico e Sara Orlando\"\n publisher=\"Maggioli Editore\"\n></mds-book>\n```\n\n#### Pages and Binding from the Catalogue Record\n\nPass the page count and the binding of the record as they are: the book takes its true depth, so a booklet and a large manual do not look alike.\n\n```html\n<mds-book src=\"/covers/guida-rapida.webp\" name=\"Guida rapida al GDPR\" pages=\"64\"></mds-book>\n\n<mds-book\n src=\"/covers/codice-appalti.webp\"\n name=\"Codice dei contratti pubblici\"\n pages=\"1000\"\n binding=\"hardcover\"\n></mds-book>\n```\n\n#### A Catalogue Grid\n\nThe book takes the width of its cell. Give the grid some gap: the turned books reach a little beyond their boxes.\n\n```html\n<div class=\"grid grid-cols-4 gap-1200\">\n <mds-book src=\"/covers/1.webp\" name=\"Creare la holding\" author=\"Ennio Vial\"></mds-book>\n <mds-book src=\"/covers/2.webp\" name=\"Chief AI Officer\" pages=\"480\"></mds-book>\n <mds-book src=\"/covers/3.webp\" name=\"Aste immobiliari e vendita forzata\"></mds-book>\n <mds-book src=\"/covers/4.webp\" name=\"Agenda dei servizi demografici 2027\"></mds-book>\n</div>\n```\n\n#### A Pose for the Layout\n\nPick the pose that suits where the book sits: `spine` in a catalogue, `front` beside a description, `lying` or `lying-turned` for a book on a desk in a hero or a banner.\n\n```html\n<mds-book src=\"/covers/manuale.webp\" name=\"Manuale\" pose=\"front\"></mds-book>\n\n<mds-book\n src=\"/covers/codice-appalti.webp\"\n name=\"Codice dei contratti pubblici\"\n binding=\"hardcover\"\n pages=\"640\"\n pose=\"lying-turned\"\n></mds-book>\n```\n\n#### A Fixed Format\n\nWith `format=\"auto\"` (the default) the book takes the proportions of its image once it loads. Set the format when the catalogue knows it, so the book has its shape before the image arrives; write any format as `WxH` in centimetres, the width first.\n\n```html\n<mds-book src=\"/covers/modulistica.webp\" name=\"Modulistica\" format=\"a4\"></mds-book>\n\n<mds-book src=\"/covers/atlante.webp\" name=\"Atlante dei comuni\" format=\"29.7x21\"></mds-book>\n```\n\n#### A Book Without a Cover Image\n\nWithout `src`, the component draws a cover with the title, the author and the publisher. Give it the colour of the series.\n\n```html\n<mds-book\n name=\"Agenda dei servizi demografici 2027\"\n publisher=\"Maggioli Editore\"\n style=\"--mds-book-color: #f2a93b; --mds-book-text-color: #ffffff\"\n></mds-book>\n```\n\n#### A Solid Spine\n\nWhen the left edge of the cover does not continue well onto the spine (a photo, a thin white border), give the spine and the board edges a colour of their own.\n\n```html\n<mds-book\n src=\"/covers/manuale.webp\"\n name=\"Manuale\"\n style=\"--mds-book-spine-color: #123a6b\"\n></mds-book>\n```\n\n#### A Book That Opens Its Product Page\n\nThe book is an image, not a control: wrap it in a link, with the link named by the book. Turning the book with a drag does not open the link; a click does.\n\n```html\n<a href=\"/catalogo/creare-la-holding\">\n <mds-book src=\"/covers/creare-la-holding.webp\" name=\"Creare la holding\" author=\"Ennio Vial\"></mds-book>\n</a>\n```\n",
3459
+ "1. Description": "The `<mds-book>` web component shows a book as a physical object, from the image of its front cover alone: front cover, spine and page block drawn in CSS 3D, turned a little so the spine shows. It is the catalogue and product-page counterpart of `<mds-img>`, for publications rather than pictures.\n\n#### Semantic Behavior\n\n- **One image of the book**: The host is a single `role=\"img\"` named by `alt`, or by `name` and `author` (\"Title by Author\", localised in el/en/es/it), or by a generic \"Book\" when there is neither. An empty `alt` marks the book as decorative (`role=\"presentation\"`). The text printed on the spine and on a drawn cover is hidden from assistive technologies, since it repeats that name.\n- **The sides come from the cover**: The spine continues the left edge of the cover image and the board edges its top and right edges, as a wraparound cover prints its design on, so no spine or back cover image is needed. Without an image they take `--mds-book-color`.\n- **A drawn cover instead of a broken image**: Without `src`, or when the image fails to load, the front shows the author, the title and the publisher, or its mark, on `--mds-book-color`. A new `src` tries again.\n- **A neutral shape while loading**: Until its image arrives, a book with `src` is drawn in a neutral surface colour, so a lazy catalogue does not flash in the colour of drawn covers.\n- **Light and shadow**: The book is seen a little from above. Each face takes the light by how it turns toward it, in a light touch that shows the volume without drawing the eye. Its shadow falls on the surface it rests on, under its tail when it stands and under its back cover when it lies, darkest where it touches and soon gone; around its outline only a halo faint enough to part a light cover from a light page.\n- **Movement**: The book rests in its `pose`. On hover it rises off the surface, its shadow fading there, and leans a little toward the pointer, with a faint sheen on the cover. A drag (mouse, pen or finger) turns it further, within limits, to show the spine or the pages, never the back, or spins a lying book on its surface; it settles back when released, or when the pointer leaves the window or the frame of the page, where its release could not reach the book. A vertical swipe still scrolls the page.\n- **Not a control**: The book has no action of its own. To make it a link, wrap it: the click that ends a drag does not follow the link, a plain click does.\n- **Reduced motion**: With the animation preference set to reduce (or the system asking for it, when there is no controller), the book keeps its resting pose: no lean, no lift, no drag.\n- **Consumption**: The consumption preference sets how much the book costs to draw. At `high` (the default, and on a page without the controller) it does everything; at `medium` it moves without the sheen and without the halo, a filter computed again on every frame; at `low` it is drawn once, in its pose, and never animated. While it moves, only opacities and transforms change, which the compositor applies without painting the faces again.\n\n#### Properties & Visual Configurations\n\n- **`pose`**: how the book is shown, after the usual shots of product photography. A drag turns it from there, and it goes back to it when released.\n - `'spine'`: standing, turned to show its spine; the default, and the one for a catalogue.\n - `'fore-edge'`: standing, turned the other way to show its pages.\n - `'front'`: facing the reader, flat, the cover as it is; the light still shows the binding when it moves.\n - `'lying'`: lying on its back, seen from above, its tail toward the reader: a book on a desk.\n - `'lying-turned'`: lying, spun on the surface to show its spine and its tail.\n\n- **`format`**: the proportions of the book, in one field that also carries the orientation.\n - `'auto'`: the proportions of the image, read once it has loaded (a square cover gives a square book); before that, and without an image, 17x24. Pick it when the image already has the true proportions.\n - `'a4'`, `'a5'`, `'b5'`: the ISO formats, portrait. Any other format is `WxH` in centimetres, the order of the two numbers being the orientation: `'17x24'` portrait, `'24x17'` landscape, `'21x21'` square. A fixed format keeps its shape before the image loads and crops small differences of the image.\n- **`pages`**: the number of pages, from the catalogue record, which sets how deep the book is against the width of its format (17 cm for `'auto'`). A short book is printed on bulky paper and a long volume on thin paper, so a page goes from 0.1 mm at 1 page to 0.05 mm at 1000 pages and beyond, in proportion: 64 pages make 6 mm, 300 pages 2.5 cm, 1000 pages 5 cm, and an A4 of the same pages looks thinner than a 17x24. A spine under 5 mm carries no text.\n- **`binding`**: how the book is built, which shows on its head, its fore edge and its spine.\n - `'paperback'`: cut flush, the cover a hairline on the same edge as the pages, a flat spine.\n - `'hardcover'`: rigid boards about 2.5 mm thick, overhanging a page block set in from them by about 3 mm, the endpapers showing in the gap, a headband, a rounded spine and a hinge groove on the front.\n- **`name`**, **`author`**, **`publisher`**: the same names as on `<mds-bibliography>`, so one catalogue record feeds both.\n- **The spine**: the title, then the author, at the head, and the publisher at the foot. Where the spine has room for two lines, at least 13.5% as deep as the book is wide (about 23 mm on a 17x24, some 270 pages in paperback), the author goes under the title, smaller, as on a thick volume.\n- **`publisher-logo`**: the mark of the publisher, printed instead of its name at the foot of the spine and of a drawn cover (a cover image carries its own). Only its shape is printed, as a mask, in `--mds-book-publisher-color`, which is the colour of the text unless set, so a mark of any colour prints in the ink of the book. Give an svg, or a png on a transparent ground; an image from another origin needs CORS headers, as any mask does. The place stays empty while the mark loads, and the name of the publisher is printed if it fails.\n- **Size**: the book is sized as an image is, in the proportions of its format: give it a width, and its height follows; give it a height, and its width follows. With neither, it fills the width of its container, as a block does; where nothing gives it a width (a row of a flex layout) it is 200 px wide. Its box is the front cover at rest: the turned book reaches a little beyond it, by a few percent of its width on each side standing, by up to a third lying spun round, so leave it some room inside a container that clips.\n",
3460
+ "2. Pattern": "Correct and idiomatic ways to use the `<mds-book>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### A Book from Its Cover\n\nThe canonical form: the cover image and the catalogue data. The title and the author name the book for assistive technologies and are printed on the spine.\n\n```html\n<mds-book\n src=\"/covers/operazioni-straordinarie.webp\"\n name=\"Operazioni straordinarie\"\n author=\"Antonio D'Amico e Sara Orlando\"\n publisher=\"Maggioli Editore\"\n></mds-book>\n```\n\n#### Pages and Binding from the Catalogue Record\n\nPass the page count and the binding of the record as they are: the book takes its true depth, so a booklet and a large manual do not look alike.\n\n```html\n<mds-book src=\"/covers/guida-rapida.webp\" name=\"Guida rapida al GDPR\" pages=\"64\"></mds-book>\n\n<mds-book\n src=\"/covers/codice-appalti.webp\"\n name=\"Codice dei contratti pubblici\"\n pages=\"1000\"\n binding=\"hardcover\"\n></mds-book>\n```\n\n#### A Catalogue Grid\n\nThe book takes the width of its cell. Give the grid some gap: the turned books reach a little beyond their boxes.\n\n```html\n<div class=\"grid grid-cols-4 gap-1200\">\n <mds-book src=\"/covers/1.webp\" name=\"Creare la holding\" author=\"Ennio Vial\"></mds-book>\n <mds-book src=\"/covers/2.webp\" name=\"Chief AI Officer\" pages=\"480\"></mds-book>\n <mds-book src=\"/covers/3.webp\" name=\"Aste immobiliari e vendita forzata\"></mds-book>\n <mds-book src=\"/covers/4.webp\" name=\"Agenda dei servizi demografici 2027\"></mds-book>\n</div>\n```\n\n#### A Pose for the Layout\n\nPick the pose that suits where the book sits: `spine` in a catalogue, `front` beside a description, `lying` or `lying-turned` for a book on a desk in a hero or a banner.\n\n```html\n<mds-book src=\"/covers/manuale.webp\" name=\"Manuale\" pose=\"front\"></mds-book>\n\n<mds-book\n src=\"/covers/codice-appalti.webp\"\n name=\"Codice dei contratti pubblici\"\n binding=\"hardcover\"\n pages=\"640\"\n pose=\"lying-turned\"\n></mds-book>\n```\n\n#### A Fixed Format\n\nWith `format=\"auto\"` (the default) the book takes the proportions of its image once it loads. Set the format when the catalogue knows it, so the book has its shape before the image arrives; write any format as `WxH` in centimetres, the width first.\n\n```html\n<mds-book src=\"/covers/modulistica.webp\" name=\"Modulistica\" format=\"a4\"></mds-book>\n\n<mds-book src=\"/covers/atlante.webp\" name=\"Atlante dei comuni\" format=\"29.7x21\"></mds-book>\n```\n\n#### A Book Without a Cover Image\n\nWithout `src`, the component draws a cover with the title, the author and the publisher. Give it the colour of the series.\n\n```html\n<mds-book\n name=\"Agenda dei servizi demografici 2027\"\n publisher=\"Maggioli Editore\"\n style=\"--mds-book-color: #f2a93b; --mds-book-text-color: #ffffff\"\n></mds-book>\n```\n\n#### The Mark of the Publisher\n\nGive the mark of the publisher instead of printing its name: it goes at the foot of the spine, and of the cover when the component draws it. Its shape is printed in the colour of the text, or in `--mds-book-publisher-color`; keep `publisher`, printed if the mark does not load.\n\n```html\n<mds-book\n name=\"Agenda dei servizi demografici 2027\"\n author=\"Redazione Maggioli\"\n publisher=\"Maggioli Editore\"\n publisher-logo=\"/logos/maggioli-editore.svg\"\n style=\"--mds-book-color: #f2a93b; --mds-book-text-color: #ffffff\"\n></mds-book>\n```\n\n#### A Solid Spine\n\nWhen the left edge of the cover does not continue well onto the spine (a photo, a thin white border), give the spine and the board edges a colour of their own.\n\n```html\n<mds-book\n src=\"/covers/manuale.webp\"\n name=\"Manuale\"\n style=\"--mds-book-spine-color: #123a6b\"\n></mds-book>\n```\n\n#### A Book That Opens Its Product Page\n\nThe book is an image, not a control: wrap it in a link, with the link named by the book. Turning the book with a drag does not open the link; a click does.\n\n```html\n<a href=\"/catalogo/creare-la-holding\">\n <mds-book src=\"/covers/creare-la-holding.webp\" name=\"Creare la holding\" author=\"Ennio Vial\"></mds-book>\n</a>\n```\n",
3417
3461
  "3. Antipattern": "Common incorrect uses of `<mds-book>`. 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/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Use the `title` Attribute for the Title\n\n`title` is the native tooltip of every element: it shows a tooltip and prints nothing on the book. The title of the book is `name`.\n\n```html\n<!-- INCORRECT -->\n<mds-book src=\"/covers/manuale.webp\" title=\"Manuale\"></mds-book>\n\n<!-- CORRECT -->\n<mds-book src=\"/covers/manuale.webp\" name=\"Manuale\"></mds-book>\n```\n\n#### Do Not Draw the 3D With `<mds-img>` and CSS Transforms\n\nA transformed `<mds-img>` is a tilted flat picture: no spine, no pages, no drawn cover when the image fails, no reduced-motion handling.\n\n```html\n<!-- INCORRECT -->\n<mds-img src=\"/covers/manuale.webp\" alt=\"Manuale\" style=\"transform: perspective(600px) rotateY(25deg)\"></mds-img>\n\n<!-- CORRECT -->\n<mds-book src=\"/covers/manuale.webp\" name=\"Manuale\"></mds-book>\n```\n\n#### Do Not Turn the Book With a Transform\n\nA transform on the host turns the flat box the book is drawn in: the light on the faces, the shadow and the drag still work from the pose, which no longer matches. Pick a `pose`.\n\n```html\n<!-- INCORRECT -->\n<mds-book src=\"/covers/manuale.webp\" name=\"Manuale\" style=\"transform: rotateX(60deg)\"></mds-book>\n\n<!-- CORRECT -->\n<mds-book src=\"/covers/manuale.webp\" name=\"Manuale\" pose=\"lying\"></mds-book>\n```\n\n#### Do Not Set Both a Width and a Height\n\nThe book keeps the proportions of its format, as an image does: one dimension sets the other. Two that disagree leave the book as wide as its box and the box with a gap or an overflow.\n\n```html\n<!-- INCORRECT -->\n<mds-book src=\"/covers/manuale.webp\" name=\"Manuale\" style=\"width: 220px; height: 220px\"></mds-book>\n\n<!-- CORRECT -->\n<mds-book src=\"/covers/manuale.webp\" name=\"Manuale\" style=\"height: 320px\"></mds-book>\n```\n\n#### Do Not Write a Landscape Format as a Separate Orientation\n\nThere is no orientation prop: the order of the two numbers of `format` is the orientation.\n\n```html\n<!-- INCORRECT -->\n<mds-book name=\"Atlante\" format=\"a4\" orientation=\"landscape\"></mds-book>\n\n<!-- CORRECT -->\n<mds-book name=\"Atlante\" format=\"29.7x21\"></mds-book>\n```\n\n#### Do Not Repeat the Name Next to the Book for Assistive Technologies\n\nThe book is already named after `name` and `author`. A visible caption that repeats them makes screen readers read the title twice: mark the book decorative with `alt=\"\"` when a caption names it.\n\n```html\n<!-- INCORRECT -->\n<figure>\n <mds-book src=\"/covers/manuale.webp\" name=\"Manuale\"></mds-book>\n <figcaption>Manuale</figcaption>\n</figure>\n\n<!-- CORRECT -->\n<figure>\n <mds-book src=\"/covers/manuale.webp\" name=\"Manuale\" alt=\"\"></mds-book>\n <figcaption>Manuale</figcaption>\n</figure>\n```\n"
3418
3462
  },
3419
3463
  "props": [
@@ -3454,7 +3498,7 @@
3454
3498
  "mutable": false,
3455
3499
  "attr": "author",
3456
3500
  "reflectToAttr": false,
3457
- "docs": "The author, printed on the spine and on the cover drawn when there is no image",
3501
+ "docs": "The author, printed on the cover drawn when there is no image, above the title, and on the\nspine after the title, or under it where the spine has room for two lines",
3458
3502
  "docsTags": [],
3459
3503
  "values": [
3460
3504
  {
@@ -3729,7 +3773,7 @@
3729
3773
  "mutable": false,
3730
3774
  "attr": "publisher",
3731
3775
  "reflectToAttr": false,
3732
- "docs": "The publisher, printed at the foot of the spine and of the cover drawn when there is no image",
3776
+ "docs": "The publisher, printed at the foot of the spine and of the cover drawn when there is no\nimage, unless its `publisher-logo` is printed there instead",
3733
3777
  "docsTags": [],
3734
3778
  "values": [
3735
3779
  {
@@ -3744,6 +3788,37 @@
3744
3788
  "getter": false,
3745
3789
  "setter": false
3746
3790
  },
3791
+ {
3792
+ "name": "publisherLogo",
3793
+ "type": "string | undefined",
3794
+ "complexType": {
3795
+ "original": "string",
3796
+ "resolved": "string | undefined",
3797
+ "references": {}
3798
+ },
3799
+ "mutable": false,
3800
+ "attr": "publisher-logo",
3801
+ "reflectToAttr": false,
3802
+ "docs": "The mark of the publisher, printed instead of its name at the foot of the spine and of the\ncover drawn when there is no image: the path to an svg, or a png on a transparent ground.\nIts shape is printed, not its colours, in `--mds-book-publisher-color`. An image from\nanother origin needs CORS headers, as any mask does; one that does not load leaves the name",
3803
+ "docsTags": [
3804
+ {
3805
+ "name": "example",
3806
+ "text": "'/logos/maggioli-editore.svg'"
3807
+ }
3808
+ ],
3809
+ "values": [
3810
+ {
3811
+ "type": "string"
3812
+ },
3813
+ {
3814
+ "type": "undefined"
3815
+ }
3816
+ ],
3817
+ "optional": true,
3818
+ "required": false,
3819
+ "getter": false,
3820
+ "setter": false
3821
+ },
3747
3822
  {
3748
3823
  "name": "src",
3749
3824
  "type": "string | undefined",
@@ -3841,6 +3916,13 @@
3841
3916
  "docs": "The colour of the page block.",
3842
3917
  "visibility": "internal"
3843
3918
  },
3919
+ {
3920
+ "name": "--mds-book-publisher-color",
3921
+ "annotation": "prop",
3922
+ "docs": "The colour of the publisher at the foot of the spine and of the cover drawn when there is no image, its mark or its name. Unset, the colour of the text.",
3923
+ "visibility": "public",
3924
+ "static": true
3925
+ },
3844
3926
  {
3845
3927
  "name": "--mds-book-spine-color",
3846
3928
  "annotation": "prop",
@@ -3866,7 +3948,8 @@
3866
3948
  "states": [],
3867
3949
  "dependents": [],
3868
3950
  "dependencies": [],
3869
- "dependencyGraph": {}
3951
+ "dependencyGraph": {},
3952
+ "storybook": "ui-book--docs"
3870
3953
  },
3871
3954
  {
3872
3955
  "filePath": "src/components/mds-breadcrumb/mds-breadcrumb.tsx",
@@ -4037,7 +4120,8 @@
4037
4120
  "mds-icon",
4038
4121
  "mds-text"
4039
4122
  ]
4040
- }
4123
+ },
4124
+ "storybook": "ui-breadcrumb--docs"
4041
4125
  },
4042
4126
  {
4043
4127
  "filePath": "src/components/mds-breadcrumb-item/mds-breadcrumb-item.tsx",
@@ -4204,7 +4288,8 @@
4204
4288
  "mds-icon",
4205
4289
  "mds-text"
4206
4290
  ]
4207
- }
4291
+ },
4292
+ "storybook": "ui-breadcrumb-breadcrumb-item--docs"
4208
4293
  },
4209
4294
  {
4210
4295
  "filePath": "src/components/mds-button/mds-button.tsx",
@@ -5150,7 +5235,8 @@
5150
5235
  "mds-url-view": [
5151
5236
  "mds-button"
5152
5237
  ]
5153
- }
5238
+ },
5239
+ "storybook": "ui-button--docs"
5154
5240
  },
5155
5241
  {
5156
5242
  "filePath": "src/components/mds-button-dropdown/mds-button-dropdown.tsx",
@@ -5764,7 +5850,8 @@
5764
5850
  "mds-icon",
5765
5851
  "mds-text"
5766
5852
  ]
5767
- }
5853
+ },
5854
+ "storybook": "ui-button-dropdown--docs"
5768
5855
  },
5769
5856
  {
5770
5857
  "filePath": "src/components/mds-button-group/mds-button-group.tsx",
@@ -5802,7 +5889,8 @@
5802
5889
  "states": [],
5803
5890
  "dependents": [],
5804
5891
  "dependencies": [],
5805
- "dependencyGraph": {}
5892
+ "dependencyGraph": {},
5893
+ "storybook": "ui-button-group--docs"
5806
5894
  },
5807
5895
  {
5808
5896
  "filePath": "src/components/mds-calendar/mds-calendar.tsx",
@@ -6432,7 +6520,8 @@
6432
6520
  "mds-input-date-range": [
6433
6521
  "mds-calendar"
6434
6522
  ]
6435
- }
6523
+ },
6524
+ "storybook": "ui-calendar--docs"
6436
6525
  },
6437
6526
  {
6438
6527
  "filePath": "src/components/mds-calendar-cell/mds-calendar-cell.tsx",
@@ -7007,7 +7096,8 @@
7007
7096
  "mds-calendar": [
7008
7097
  "mds-calendar-cell"
7009
7098
  ]
7010
- }
7099
+ },
7100
+ "storybook": "ui-calendar-cell--docs"
7011
7101
  },
7012
7102
  {
7013
7103
  "filePath": "src/components/mds-card/mds-card.tsx",
@@ -7127,7 +7217,8 @@
7127
7217
  "states": [],
7128
7218
  "dependents": [],
7129
7219
  "dependencies": [],
7130
- "dependencyGraph": {}
7220
+ "dependencyGraph": {},
7221
+ "storybook": "layout-card--docs"
7131
7222
  },
7132
7223
  {
7133
7224
  "filePath": "src/components/mds-card-content/mds-card-content.tsx",
@@ -7165,7 +7256,8 @@
7165
7256
  "states": [],
7166
7257
  "dependents": [],
7167
7258
  "dependencies": [],
7168
- "dependencyGraph": {}
7259
+ "dependencyGraph": {},
7260
+ "storybook": "layout-card-content--docs"
7169
7261
  },
7170
7262
  {
7171
7263
  "filePath": "src/components/mds-card-footer/mds-card-footer.tsx",
@@ -7203,7 +7295,8 @@
7203
7295
  "states": [],
7204
7296
  "dependents": [],
7205
7297
  "dependencies": [],
7206
- "dependencyGraph": {}
7298
+ "dependencyGraph": {},
7299
+ "storybook": "layout-card-footer--docs"
7207
7300
  },
7208
7301
  {
7209
7302
  "filePath": "src/components/mds-card-header/mds-card-header.tsx",
@@ -7249,7 +7342,8 @@
7249
7342
  "states": [],
7250
7343
  "dependents": [],
7251
7344
  "dependencies": [],
7252
- "dependencyGraph": {}
7345
+ "dependencyGraph": {},
7346
+ "storybook": "layout-card-header--docs"
7253
7347
  },
7254
7348
  {
7255
7349
  "filePath": "src/components/mds-card-media/mds-card-media.tsx",
@@ -7304,7 +7398,8 @@
7304
7398
  "states": [],
7305
7399
  "dependents": [],
7306
7400
  "dependencies": [],
7307
- "dependencyGraph": {}
7401
+ "dependencyGraph": {},
7402
+ "storybook": "layout-card-media--docs"
7308
7403
  },
7309
7404
  {
7310
7405
  "filePath": "src/components/mds-chip/mds-chip.tsx",
@@ -7848,7 +7943,8 @@
7848
7943
  "mds-policy-ai": [
7849
7944
  "mds-chip"
7850
7945
  ]
7851
- }
7946
+ },
7947
+ "storybook": "ui-chip--docs"
7852
7948
  },
7853
7949
  {
7854
7950
  "filePath": "src/components/mds-details/mds-details.tsx",
@@ -7999,7 +8095,8 @@
7999
8095
  "states": [],
8000
8096
  "dependents": [],
8001
8097
  "dependencies": [],
8002
- "dependencyGraph": {}
8098
+ "dependencyGraph": {},
8099
+ "storybook": "ui-details--docs"
8003
8100
  },
8004
8101
  {
8005
8102
  "filePath": "src/components/mds-dropdown/mds-dropdown.tsx",
@@ -8712,7 +8809,8 @@
8712
8809
  "mds-pref-theme": [
8713
8810
  "mds-dropdown"
8714
8811
  ]
8715
- }
8812
+ },
8813
+ "storybook": "ui-dropdown--docs"
8716
8814
  },
8717
8815
  {
8718
8816
  "filePath": "src/components/mds-emoji/mds-emoji.tsx",
@@ -9217,7 +9315,8 @@
9217
9315
  "states": [],
9218
9316
  "dependents": [],
9219
9317
  "dependencies": [],
9220
- "dependencyGraph": {}
9318
+ "dependencyGraph": {},
9319
+ "storybook": "ui-emoji--docs"
9221
9320
  },
9222
9321
  {
9223
9322
  "filePath": "src/components/mds-entity/mds-entity.tsx",
@@ -9590,7 +9689,8 @@
9590
9689
  "mds-icon",
9591
9690
  "mds-text"
9592
9691
  ]
9593
- }
9692
+ },
9693
+ "storybook": "ui-entity--docs"
9594
9694
  },
9595
9695
  {
9596
9696
  "filePath": "src/components/mds-file/mds-file.tsx",
@@ -10073,7 +10173,8 @@
10073
10173
  "mds-badge": [
10074
10174
  "mds-text"
10075
10175
  ]
10076
- }
10176
+ },
10177
+ "storybook": "ui-file--docs"
10077
10178
  },
10078
10179
  {
10079
10180
  "filePath": "src/components/mds-file-preview/mds-file-preview.tsx",
@@ -10863,7 +10964,8 @@
10863
10964
  "mds-input-upload": [
10864
10965
  "mds-file-preview"
10865
10966
  ]
10866
- }
10967
+ },
10968
+ "storybook": "ui-file-preview--docs"
10867
10969
  },
10868
10970
  {
10869
10971
  "filePath": "src/components/mds-filter/mds-filter.tsx",
@@ -11060,6 +11162,12 @@
11060
11162
  "docs": "Sets the scroll-behavior animation;",
11061
11163
  "visibility": "internal"
11062
11164
  },
11165
+ {
11166
+ "name": "--mds-filter-label-gap",
11167
+ "annotation": "prop",
11168
+ "docs": "Sets the gap between the label and the items row area",
11169
+ "visibility": "internal"
11170
+ },
11063
11171
  {
11064
11172
  "name": "--mds-filter-label-padding",
11065
11173
  "annotation": "prop",
@@ -11107,7 +11215,8 @@
11107
11215
  "mds-icon",
11108
11216
  "mds-text"
11109
11217
  ]
11110
- }
11218
+ },
11219
+ "storybook": "ui-filter--docs"
11111
11220
  },
11112
11221
  {
11113
11222
  "filePath": "src/components/mds-filter-item/mds-filter-item.tsx",
@@ -11347,7 +11456,8 @@
11347
11456
  "mds-filter": [
11348
11457
  "mds-filter-item"
11349
11458
  ]
11350
- }
11459
+ },
11460
+ "storybook": "ui-filter-filter-item--docs"
11351
11461
  },
11352
11462
  {
11353
11463
  "filePath": "src/components/mds-header/mds-header.tsx",
@@ -11375,7 +11485,7 @@
11375
11485
  ],
11376
11486
  "usage": {
11377
11487
  "1. Description": "The `<mds-header>` web component is the top-level page header container of the Magma Design System. It is a compound parent that wraps one or more `<mds-header-bar>` elements, orchestrating their scroll-driven appearance, auto-hide visibility, and an optional mobile menu rendered as a side modal.\n\n#### Semantic Behavior\n\n- **Compound parent**: Hosts `<mds-header-bar>` children in the default slot and relays its `menu` and `nav` settings down to the bar.\n- **Mobile menu**: A `[slot=\"menu\"]` child is rendered inside a right-positioned modal. When it is absent there is no modal, and the bar receives `menu=\"none\"` whatever `menu` says, so no hamburger shows that would open nothing.\n- **Open/close control**: The menu modal is opened by the bar's hamburger or programmatically via the `setOpened()` method; when the user closes it, `mdsHeaderClose` is emitted (with the bound bar).\n- **Scroll-driven appearance**: When `appearanceSet` names two appearances, `appearance` swaps between them as the page scrolls past its pixel threshold (300 when the third token is omitted).\n- **Auto-hide on scroll**: When `autoHide` is set, scrolling down past that pixel offset hides the bar and scrolling up reveals it again, governed by `threshold` as the directional margin.\n- **Visibility event**: Any change to `visibility` (`'visible'`/`'hidden'`) emits `mdsHeaderVisibilityChange`, whose `detail.visibility` is that string.\n\n#### Properties & Visual Configurations\n\n- **`appearance`** is the bar's current visual mode (`'stripe'` or `'inline'`) and is mutable because the component rewrites it as the page scrolls.\n- **`appearanceSet`** is a space/comma-separated string declaring scroll behavior as three tokens: initial appearance, changed appearance, and the `scrollY` pixel threshold (e.g. `\"stripe, inline 200\"`). Use it instead of `appearance` when the header should transform on scroll; `appearance` alone keeps a fixed look.\n- **`autoHide`** is the pixel offset past which the bar starts hiding on downward scroll; leave it unset to keep the bar always present.\n- **`threshold`** tunes how many pixels of opposite-direction scroll are required to flip the auto-hide state - raise it to make hide/show less twitchy.\n- **`menu`** and **`nav`** select on which viewports the hamburger menu and the navigation are shown (`'all'`, `'desktop'`, `'mobile'`, `'none'`); they are relayed to the child bar.\n- **`hideBackdrop`** removes the blurred backdrop layer shown behind the bar when its appearance is `'inline'`.\n- **`visibility`** reflects the current shown/hidden state of the bar and can be set to force it.\n",
11378
- "2. Pattern": "Correct and idiomatic ways to use the `<mds-header>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Minimal Header with Navigation Bar\n\nThe default form. Place exactly one `<mds-header-bar>` in the default slot. The bar receives the `menu` and `nav` breakpoint settings from the parent automatically; without a `menu` slot set `menu=\"none\"`, or the bar shows a hamburger that opens nothing.\n\n```html\n<mds-header menu=\"none\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button slot=\"nav\" label=\"Registrati\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-header-bar>\n</mds-header>\n```\n\n#### Mobile Menu via the `menu` Slot\n\nProvide a `[slot=\"menu\"]` child to enable the hamburger-triggered side modal. When this slot is filled, the mobile menu icon is shown according to the `menu` breakpoint prop; without it the hamburger still shows and opens nothing, so set `menu=\"none\"`.\n\n```html\n<mds-header menu=\"mobile\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </mds-header-bar>\n\n <div slot=\"menu\">\n <div class=\"p-600\">\n <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button label=\"Registrati\" variant=\"primary\" tone=\"strong\"></mds-button>\n </div>\n </div>\n</mds-header>\n```\n\n#### Inline Appearance (Floating Bar)\n\nSet `appearance=\"inline\"` to detach the bar from the top edge and give it a rounded, floating look. A blurred backdrop is shown by default; add `hide-backdrop` to remove it.\n\n```html\n<mds-header appearance=\"inline\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </mds-header-bar>\n</mds-header>\n```\n\n#### Scroll-Driven Appearance Change via `appearance-set`\n\nUse `appearance-set` to declare an initial appearance, a changed appearance, and a scroll threshold in pixels. The component swaps `appearance` automatically as the page scrolls past the threshold - no JavaScript needed. Do not combine `appearance-set` with manual writes to `appearance`.\n\n```html\n<!-- Starts inline (floating), switches to stripe (full-width) after 300 px of scroll -->\n<mds-header appearance-set=\"inline, stripe 300\" appearance=\"inline\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n </mds-header-bar>\n</mds-header>\n```\n\n#### Auto-Hide on Downward Scroll\n\nSet `auto-hide` to the pixel offset at which the bar should start hiding when the user scrolls down. The bar reappears when the user scrolls back up. Use `threshold` (default `1`) to control how many pixels of reverse-scroll are required before the bar snaps back - raise it to reduce twitchiness.\n\n```html\n<mds-header auto-hide=\"300\" threshold=\"10\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </mds-header-bar>\n</mds-header>\n```\n\n#### Controlling Menu and Nav Breakpoints\n\n`menu` controls on which viewports the hamburger icon is visible; `nav` controls on which viewports the inline navigation is visible. Both accept `'all'`, `'desktop'`, `'mobile'`, or `'none'`.\n\n```html\n<!-- Hamburger shown on all screen sizes; inline nav shown only on desktop -->\n<mds-header menu=\"all\" nav=\"desktop\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </mds-header-bar>\n\n <div slot=\"menu\">\n <div class=\"p-600\">\n <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </div>\n </div>\n</mds-header>\n```\n\n#### Reacting to Visibility Changes\n\nListen for `mdsHeaderVisibilityChange` to know when the bar is hidden or shown by auto-hide. The event detail carries `visibility` as the string `'visible'` or `'hidden'`.\n\n```html\n<mds-header auto-hide=\"200\" id=\"siteHeader\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n </mds-header-bar>\n</mds-header>\n\n<script>\n document.getElementById('siteHeader').addEventListener('mdsHeaderVisibilityChange', (e) => {\n console.log('header visibile:', e.detail.visibility);\n });\n</script>\n```\n\n#### Reacting to Mobile Menu Close\n\nListen for `mdsHeaderClose` to run cleanup logic when the side modal is dismissed. The event detail carries the bound `<mds-header-bar>` reference.\n\n```html\n<mds-header id=\"siteHeader\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n </mds-header-bar>\n <div slot=\"menu\">\n <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </div>\n</mds-header>\n\n<script>\n document.getElementById('siteHeader').addEventListener('mdsHeaderClose', (e) => {\n console.log('menu chiuso, bar:', e.detail.bar);\n });\n</script>\n```\n\n#### Programmatic Open/Close via `setOpened()`\n\nUse the `setOpened()` method to open or close the mobile menu from JavaScript - for example after a navigation event inside the menu panel.\n\n```html\n<mds-header id=\"siteHeader\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n </mds-header-bar>\n <div slot=\"menu\">\n <mds-button label=\"Vai alla home\" id=\"homeBtn\" variant=\"primary\" tone=\"strong\"></mds-button>\n </div>\n</mds-header>\n\n<script>\n document.getElementById('homeBtn').addEventListener('click', async () => {\n window.location.href = '/';\n await document.getElementById('siteHeader').setOpened(false);\n });\n</script>\n```\n\n#### Styling Customization\n\nCustomize the header through its public `--mds-header-*` CSS custom properties. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast continue to work. `--mds-header-color` also colors the icons, the hamburger of the child `mds-header-bar` included.\n\n```css\nmds-header {\n --mds-header-color: rgb(var(--magma-text-muted));\n --mds-header-z-index: 200;\n}\n\n/* Inline appearance: wider floating margin on desktop */\nmds-header[appearance='inline'] {\n --mds-header-inline-margin: 2rem;\n}\n```\n",
11488
+ "2. Pattern": "Correct and idiomatic ways to use the `<mds-header>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Minimal Header with Navigation Bar\n\nThe default form. Place exactly one `<mds-header-bar>` in the default slot. The bar receives the `menu` and `nav` breakpoint settings from the parent automatically; without a `menu` slot it receives `menu=\"none\"`, so it shows no hamburger that would open nothing.\n\n```html\n<mds-header>\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button slot=\"nav\" label=\"Registrati\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-header-bar>\n</mds-header>\n```\n\n#### Mobile Menu via the `menu` Slot\n\nProvide a `[slot=\"menu\"]` child to enable the hamburger-triggered side modal. When this slot is filled, the mobile menu icon is shown according to the `menu` breakpoint prop; without it the bar receives `menu=\"none\"` whatever `menu` says, and shows no hamburger.\n\n```html\n<mds-header menu=\"mobile\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </mds-header-bar>\n\n <div slot=\"menu\">\n <div class=\"p-600\">\n <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button label=\"Registrati\" variant=\"primary\" tone=\"strong\"></mds-button>\n </div>\n </div>\n</mds-header>\n```\n\n#### Inline Appearance (Floating Bar)\n\nSet `appearance=\"inline\"` to detach the bar from the top edge and give it a rounded, floating look. A blurred backdrop is shown by default; add `hide-backdrop` to remove it.\n\n```html\n<mds-header appearance=\"inline\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </mds-header-bar>\n</mds-header>\n```\n\n#### Scroll-Driven Appearance Change via `appearance-set`\n\nUse `appearance-set` to declare an initial appearance, a changed appearance, and a scroll threshold in pixels. The component swaps `appearance` automatically as the page scrolls past the threshold - no JavaScript needed. Do not combine `appearance-set` with manual writes to `appearance`.\n\n```html\n<!-- Starts inline (floating), switches to stripe (full-width) after 300 px of scroll -->\n<mds-header appearance-set=\"inline, stripe 300\" appearance=\"inline\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n </mds-header-bar>\n</mds-header>\n```\n\n#### Auto-Hide on Downward Scroll\n\nSet `auto-hide` to the pixel offset at which the bar should start hiding when the user scrolls down. The bar reappears when the user scrolls back up. Use `threshold` (default `1`) to control how many pixels of reverse-scroll are required before the bar snaps back - raise it to reduce twitchiness.\n\n```html\n<mds-header auto-hide=\"300\" threshold=\"10\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </mds-header-bar>\n</mds-header>\n```\n\n#### Controlling Menu and Nav Breakpoints\n\n`menu` controls on which viewports the hamburger icon is visible; `nav` controls on which viewports the inline navigation is visible. Both accept `'all'`, `'desktop'`, `'mobile'`, or `'none'`.\n\n```html\n<!-- Hamburger shown on all screen sizes; inline nav shown only on desktop -->\n<mds-header menu=\"all\" nav=\"desktop\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </mds-header-bar>\n\n <div slot=\"menu\">\n <div class=\"p-600\">\n <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </div>\n </div>\n</mds-header>\n```\n\n#### Reacting to Visibility Changes\n\nListen for `mdsHeaderVisibilityChange` to know when the bar is hidden or shown by auto-hide. The event detail carries `visibility` as the string `'visible'` or `'hidden'`.\n\n```html\n<mds-header auto-hide=\"200\" id=\"siteHeader\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n </mds-header-bar>\n</mds-header>\n\n<script>\n document.getElementById('siteHeader').addEventListener('mdsHeaderVisibilityChange', (e) => {\n console.log('header visibile:', e.detail.visibility);\n });\n</script>\n```\n\n#### Reacting to Mobile Menu Close\n\nListen for `mdsHeaderClose` to run cleanup logic when the side modal is dismissed. The event detail carries the bound `<mds-header-bar>` reference.\n\n```html\n<mds-header id=\"siteHeader\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n </mds-header-bar>\n <div slot=\"menu\">\n <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </div>\n</mds-header>\n\n<script>\n document.getElementById('siteHeader').addEventListener('mdsHeaderClose', (e) => {\n console.log('menu chiuso, bar:', e.detail.bar);\n });\n</script>\n```\n\n#### Programmatic Open/Close via `setOpened()`\n\nUse the `setOpened()` method to open or close the mobile menu from JavaScript - for example after a navigation event inside the menu panel.\n\n```html\n<mds-header id=\"siteHeader\">\n <mds-header-bar>\n <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n </mds-header-bar>\n <div slot=\"menu\">\n <mds-button label=\"Vai alla home\" id=\"homeBtn\" variant=\"primary\" tone=\"strong\"></mds-button>\n </div>\n</mds-header>\n\n<script>\n document.getElementById('homeBtn').addEventListener('click', async () => {\n window.location.href = '/';\n await document.getElementById('siteHeader').setOpened(false);\n });\n</script>\n```\n\n#### Styling Customization\n\nCustomize the header through its public `--mds-header-*` CSS custom properties. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast continue to work. `--mds-header-color` also colors the icons, the hamburger of the child `mds-header-bar` included.\n\n```css\nmds-header {\n --mds-header-color: rgb(var(--magma-text-muted));\n --mds-header-z-index: 200;\n}\n\n/* Inline appearance: wider floating margin on desktop */\nmds-header[appearance='inline'] {\n --mds-header-inline-margin: 2rem;\n}\n```\n",
11379
11489
  "3. Antipattern": "Common incorrect uses of `<mds-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/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Place `<mds-header-bar>` Outside `<mds-header>`\n\n`<mds-header-bar>` is a compound child; it must be a direct slot child of `<mds-header>`, which relays breakpoint and appearance state down to it. Using the bar standalone breaks that communication: its hamburger has no menu to open, and appearance and auto-hide do not apply.\n\n```html\n<!-- INCORRECT -->\n<mds-header-bar>\n <mds-img src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n</mds-header-bar>\n\n<!-- CORRECT -->\n<mds-header>\n <mds-header-bar>\n <mds-img src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n </mds-header-bar>\n</mds-header>\n```\n\n#### Do Not Drive Scroll Appearance with JavaScript When `appearance-set` Is Available\n\nManually toggling `appearance` on a scroll listener duplicates what `appearance-set` already handles declaratively, and once `appearance-set` is also set the component's own scroll handler rewrites `appearance` on every scroll.\n\n```html\n<!-- INCORRECT -->\n<mds-header id=\"hdr\" appearance=\"inline\">\n <mds-header-bar>...</mds-header-bar>\n</mds-header>\n<script>\n window.addEventListener('scroll', () => {\n document.getElementById('hdr').appearance = window.scrollY > 300 ? 'stripe' : 'inline';\n });\n</script>\n\n<!-- CORRECT -->\n<mds-header appearance-set=\"inline, stripe 300\" appearance=\"inline\">\n <mds-header-bar>...</mds-header-bar>\n</mds-header>\n```\n\n#### Do Not Omit the `menu` Slot When Providing a Hamburger-Only Nav\n\nIf no `[slot=\"menu\"]` child is present there is no modal to open, so the bar shows no hamburger icon whatever `menu` says: on the viewports where `nav` hides the navigation, nothing is left to navigate with. Always provide menu content when you want the mobile toggle to be visible.\n\n```html\n<!-- INCORRECT: no hamburger and, on mobile, no navigation -->\n<mds-header menu=\"mobile\">\n <mds-header-bar>\n <mds-img src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </mds-header-bar>\n</mds-header>\n\n<!-- CORRECT -->\n<mds-header menu=\"mobile\">\n <mds-header-bar>\n <mds-img src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </mds-header-bar>\n <div slot=\"menu\">\n <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n </div>\n</mds-header>\n```\n\n#### Do Not Listen to Native `scroll` Events to Detect Auto-Hide State\n\nThe component already emits `mdsHeaderVisibilityChange` when the bar flips between hidden and visible. Attaching a second `scroll` listener couples your code to the same threshold logic and risks running out of sync.\n\n```html\n<!-- INCORRECT -->\n<mds-header auto-hide=\"300\" id=\"hdr\">\n <mds-header-bar>...</mds-header-bar>\n</mds-header>\n<script>\n window.addEventListener('scroll', () => {\n const hidden = window.scrollY > 300;\n document.body.classList.toggle('header-hidden', hidden);\n });\n</script>\n\n<!-- CORRECT -->\n<mds-header auto-hide=\"300\" id=\"hdr\">\n <mds-header-bar>...</mds-header-bar>\n</mds-header>\n<script>\n document.getElementById('hdr').addEventListener('mdsHeaderVisibilityChange', (e) => {\n document.body.classList.toggle('header-hidden', e.detail.visibility === 'hidden');\n });\n</script>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Internal Modal\n\nThe side-modal container is exposed as `::part(menu)` and its stacking is controllable via `--mds-header-z-index`. Do not use `>>>`, `/deep/`, or undocumented internal selectors.\n\n```css\n/* INCORRECT */\nmds-header >>> .menu mds-modal {\n background: red;\n}\n\n/* CORRECT */\nmds-header {\n --mds-header-z-index: 500;\n}\nmds-header::part(menu) {\n /* documented part - safe to target */\n}\n```\n"
11380
11490
  },
11381
11491
  "props": [
@@ -11849,7 +11959,8 @@
11849
11959
  "mds-icon",
11850
11960
  "mds-text"
11851
11961
  ]
11852
- }
11962
+ },
11963
+ "storybook": "ui-header--docs"
11853
11964
  },
11854
11965
  {
11855
11966
  "filePath": "src/components/mds-header-bar/mds-header-bar.tsx",
@@ -12100,7 +12211,8 @@
12100
12211
  "mds-icon",
12101
12212
  "mds-text"
12102
12213
  ]
12103
- }
12214
+ },
12215
+ "storybook": "ui-header-header-bar--docs"
12104
12216
  },
12105
12217
  {
12106
12218
  "filePath": "src/components/mds-help/mds-help.tsx",
@@ -12331,7 +12443,8 @@
12331
12443
  "mds-policy-ai": [
12332
12444
  "mds-help"
12333
12445
  ]
12334
- }
12446
+ },
12447
+ "storybook": "ui-help--docs"
12335
12448
  },
12336
12449
  {
12337
12450
  "filePath": "src/components/mds-horizontal-scroll/mds-horizontal-scroll.tsx",
@@ -12625,7 +12738,8 @@
12625
12738
  "mds-icon",
12626
12739
  "mds-text"
12627
12740
  ]
12628
- }
12741
+ },
12742
+ "storybook": "layout-horizontal-scroll--docs"
12629
12743
  },
12630
12744
  {
12631
12745
  "filePath": "src/components/mds-hr/mds-hr.tsx",
@@ -12654,7 +12768,8 @@
12654
12768
  "states": [],
12655
12769
  "dependents": [],
12656
12770
  "dependencies": [],
12657
- "dependencyGraph": {}
12771
+ "dependencyGraph": {},
12772
+ "storybook": "ui-hr--docs"
12658
12773
  },
12659
12774
  {
12660
12775
  "filePath": "src/components/mds-icon/mds-icon.tsx",
@@ -12858,7 +12973,8 @@
12858
12973
  "mds-usage": [
12859
12974
  "mds-icon"
12860
12975
  ]
12861
- }
12976
+ },
12977
+ "storybook": "design-icon--docs"
12862
12978
  },
12863
12979
  {
12864
12980
  "filePath": "src/components/mds-img/mds-img.tsx",
@@ -13331,7 +13447,8 @@
13331
13447
  "mds-push-notification-item": [
13332
13448
  "mds-img"
13333
13449
  ]
13334
- }
13450
+ },
13451
+ "storybook": "ui-image--docs"
13335
13452
  },
13336
13453
  {
13337
13454
  "filePath": "src/components/mds-input/mds-input.tsx",
@@ -15025,7 +15142,8 @@
15025
15142
  "mds-input-otp": [
15026
15143
  "mds-input"
15027
15144
  ]
15028
- }
15145
+ },
15146
+ "storybook": "form-input--docs"
15029
15147
  },
15030
15148
  {
15031
15149
  "filePath": "src/components/mds-input-date/mds-input-date.tsx",
@@ -15735,7 +15853,8 @@
15735
15853
  "mds-calendar-cell": [
15736
15854
  "mds-button"
15737
15855
  ]
15738
- }
15856
+ },
15857
+ "storybook": "form-input-date--docs"
15739
15858
  },
15740
15859
  {
15741
15860
  "filePath": "src/components/mds-input-date-range/mds-input-date-range.tsx",
@@ -16304,7 +16423,8 @@
16304
16423
  "mds-calendar-cell": [
16305
16424
  "mds-button"
16306
16425
  ]
16307
- }
16426
+ },
16427
+ "storybook": "form-input-date-range--docs"
16308
16428
  },
16309
16429
  {
16310
16430
  "filePath": "src/components/mds-input-date-range-preselection/mds-input-date-range-preselection.tsx",
@@ -16502,7 +16622,8 @@
16502
16622
  "mds-icon",
16503
16623
  "mds-text"
16504
16624
  ]
16505
- }
16625
+ },
16626
+ "storybook": "form-input-date-range-preselection--docs"
16506
16627
  },
16507
16628
  {
16508
16629
  "filePath": "src/components/mds-input-field/mds-input-field.tsx",
@@ -16681,7 +16802,8 @@
16681
16802
  "mds-input-field": [
16682
16803
  "mds-text"
16683
16804
  ]
16684
- }
16805
+ },
16806
+ "storybook": "form-input-field--docs"
16685
16807
  },
16686
16808
  {
16687
16809
  "filePath": "src/components/mds-input-otp/mds-input-otp.tsx",
@@ -16697,7 +16819,7 @@
16697
16819
  ],
16698
16820
  "usage": {
16699
16821
  "1. Description": "The `<mds-input-otp>` web component is the Magma Design System control for entering one-time passcodes, rendering a row of single-digit fields that together compose a single form value. It is form-associated, so it behaves like a native input whose value is the concatenated OTP code.\n\n#### Semantic Behavior\n\n- **Form association**: The joined digits are exposed as the form value, so it submits with the surrounding `<form>` with no extra wiring. A form reset brings back the code of load, in the cells and in the form, like a native input.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: the code cannot be changed and is left out of the form, until the fieldset is enabled.\n- **Single-digit cells**: Renders `length` digit cells, each capped at one character; the host value is the concatenation of every cell.\n- **Numeric-only entry**: A key that writes anything but a digit (a letter, Space) changes nothing; a digit typed on a filled cell overwrites it.\n- **Keyboard**: Backspace empties the cell, or the previous one from an empty cell, and moves there; Delete empties the cell; the left and right arrows move between the cells. Tab and Shift+Tab leave the field, and the shortcuts (paste with Ctrl+V or Cmd+V among them) keep what the browser does with them.\n- **Auto-advance focus**: After a valid digit, focus moves to the next cell automatically; entering a digit in the last cell blurs it.\n- **Paste handling**: Pasting a code of digits (the spaces around it are dropped) distributes the digits across consecutive cells starting from the focused one; a paste with anything else in it, signs and decimal points included, is ignored.\n- **Completion + submit**: When a digit typed or pasted in the last cell completes all `length` digits and `autosubmit` is set, the owning form is submitted; digits pasted past the last cell are dropped.\n\n#### Properties & Visual Configurations\n\n- **`length`** sets how many digit cells are rendered and therefore the expected code length; it doubles as the completeness threshold for auto-submit. Defaults to `6`.\n- **`disabled`** disables every cell, like a disabled native input: the code cannot be changed and is left out of the form. The cells take the disabled look without the disabled tip, which a single-digit cell has no room for.\n- **`autosubmit`** opts into automatic form submission the moment the code is complete - use it for flows where the OTP is the only field and no explicit confirm button is needed; leave it off when the user should review or trigger submission manually.\n- **`value`** holds the current concatenated code; read it to observe progress. A value written in the markup or set by code fills the cells from the first one, as many digits as there are cells, and reaches the form.\n",
16700
- "2. Pattern": "Correct and idiomatic ways to use the `<mds-input-otp>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Default Six-Digit Code\n\nThe component renders six single-digit cells by default. Drop it into a form with a `name` attribute so the concatenated value is submitted as a named field.\n\n```html\n<form action=\"/verify\" method=\"post\">\n <mds-input-otp name=\"otp\"></mds-input-otp>\n <mds-button type=\"submit\" label=\"Verifica\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Custom Code Length\n\nSet `length` to match the expected OTP length - 4 digits for a short PIN, 8 for a longer token.\n\n```html\n<!-- Four-digit PIN -->\n<mds-input-otp name=\"pin\" length=\"4\"></mds-input-otp>\n\n<!-- Eight-digit token -->\n<mds-input-otp name=\"token\" length=\"8\"></mds-input-otp>\n```\n\n#### Auto-Submit on Completion\n\nAdd the `autosubmit` boolean attribute when the OTP is the only field and no explicit confirm button is needed. The owning form is submitted when a digit typed or pasted in the last cell completes the code - do not set `autosubmit=\"false\"` to disable it; remove the attribute instead.\n\n```html\n<form action=\"/verify\" method=\"post\">\n <mds-input-otp name=\"otp\" autosubmit></mds-input-otp>\n</form>\n```\n\n#### Reading the Value Programmatically\n\n`value` is a reflected attribute that updates as the user types. Read it directly from the element or listen for form data. Set it to fill the cells from code, for example to prefill a code the page already knows; a form reset brings back the value of load.\n\n```javascript\nconst otp = document.querySelector('mds-input-otp');\n\n// Poll current state\nconsole.log(otp.value); // e.g. \"124\" while in progress: empty cells add nothing\n\n// React on form submit\ndocument.querySelector('form').addEventListener('submit', (e) => {\n e.preventDefault();\n const data = new FormData(e.target);\n console.log('Codice OTP:', data.get('otp'));\n});\n```\n\n#### Full Authentication Flow\n\nCombine `autosubmit` with a submit handler to verify the code and reflect the result - pair with [`mds-button`](../mds-button/AGENTS.md) in await state while the request is in flight.\n\n```html\n<form id=\"otp-form\" action=\"/auth/otp\" method=\"post\">\n <mds-input-otp name=\"otp\" length=\"6\" autosubmit></mds-input-otp>\n\n <mds-button\n id=\"submit-btn\"\n type=\"submit\"\n label=\"Conferma codice\"\n variant=\"primary\"\n tone=\"strong\"\n disabled\n ></mds-button>\n</form>\n\n<script>\n const form = document.getElementById('otp-form');\n const btn = document.getElementById('submit-btn');\n const otpEl = form.querySelector('mds-input-otp');\n\n // Enable the button only once all digits are entered\n setInterval(() => {\n btn.disabled = otpEl.value.length < 6 ? true : undefined;\n }, 100);\n\n form.addEventListener('submit', async (e) => {\n e.preventDefault();\n btn.setAttribute('await', '');\n // ... send request, then remove await\n });\n</script>\n```\n\n#### Layout Alignment\n\nThe host is an `inline-flex` container. Use a utility class to center it inside a card or modal.\n\n```html\n<div class=\"flex justify-center py-600\">\n <mds-input-otp name=\"otp\"></mds-input-otp>\n</div>\n```\n",
16822
+ "2. Pattern": "Correct and idiomatic ways to use the `<mds-input-otp>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Default Six-Digit Code\n\nThe component renders six single-digit cells by default. Drop it into a form with a `name` attribute so the concatenated value is submitted as a named field; the server behind the form's `action` checks the code.\n\n```html\n<form action=\"/verify\" method=\"post\">\n <mds-input-otp name=\"otp\"></mds-input-otp>\n <mds-button type=\"submit\" label=\"Verifica\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Custom Code Length\n\nSet `length` to match the expected OTP length - 4 digits for a short PIN, 8 for a longer token.\n\n```html\n<!-- Four-digit PIN -->\n<mds-input-otp name=\"pin\" length=\"4\"></mds-input-otp>\n\n<!-- Eight-digit token -->\n<mds-input-otp name=\"token\" length=\"8\"></mds-input-otp>\n```\n\n#### Auto-Submit on Completion\n\nAdd the `autosubmit` boolean attribute when the OTP is the only field and no explicit confirm button is needed. The owning form is submitted when a digit typed or pasted in the last cell completes the code - do not set `autosubmit=\"false\"` to disable it; remove the attribute instead.\n\n```html\n<form action=\"/verify\" method=\"post\">\n <mds-input-otp name=\"otp\" autosubmit></mds-input-otp>\n</form>\n```\n\n#### Reading the Value Programmatically\n\n`value` is a reflected attribute that updates as the user types. Read it directly from the element or listen for form data. Set it to fill the cells from code, for example to prefill a code the page already knows; a form reset brings back the value of load.\n\n```javascript\nconst otp = document.querySelector('mds-input-otp');\n\n// Poll current state\nconsole.log(otp.value); // e.g. \"124\" while in progress: empty cells add nothing\n\n// React on form submit\ndocument.querySelector('form').addEventListener('submit', (e) => {\n e.preventDefault();\n const data = new FormData(e.target);\n console.log('Codice OTP:', data.get('otp'));\n});\n```\n\n#### Full Authentication Flow\n\nCombine `autosubmit` with a submit handler to verify the code and reflect the result - pair with [`mds-button`](../mds-button/AGENTS.md) in await state while the request is in flight.\n\n```html\n<form id=\"otp-form\" action=\"/auth/otp\" method=\"post\">\n <mds-input-otp name=\"otp\" length=\"6\" autosubmit></mds-input-otp>\n\n <mds-button\n id=\"submit-btn\"\n type=\"submit\"\n label=\"Conferma codice\"\n variant=\"primary\"\n tone=\"strong\"\n disabled\n ></mds-button>\n</form>\n\n<script>\n const form = document.getElementById('otp-form');\n const btn = document.getElementById('submit-btn');\n const otpEl = form.querySelector('mds-input-otp');\n\n // Enable the button only once all digits are entered\n setInterval(() => {\n btn.disabled = otpEl.value.length < 6 ? true : undefined;\n }, 100);\n\n form.addEventListener('submit', async (e) => {\n e.preventDefault();\n btn.setAttribute('await', '');\n // ... send request, then remove await\n });\n</script>\n```\n\n#### Layout Alignment\n\nThe host is an `inline-flex` container. Use a utility class to center it inside a card or modal.\n\n```html\n<div class=\"flex justify-center py-600\">\n <mds-input-otp name=\"otp\"></mds-input-otp>\n</div>\n```\n",
16701
16823
  "3. Antipattern": "Common incorrect uses of `<mds-input-otp>`. 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/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Set `autosubmit=\"false\"` to Disable Auto-Submit\n\n`autosubmit` is a boolean attribute and `mds-input-otp` is form-associated: as on a native control, any value turns it on, `\"false\"` included, so this markup submits the form as soon as the code is complete. Remove the attribute entirely to opt out.\n\n```html\n<!-- INCORRECT -->\n<mds-input-otp name=\"otp\" autosubmit=\"false\"></mds-input-otp>\n\n<!-- CORRECT -->\n<mds-input-otp name=\"otp\"></mds-input-otp>\n```\n\n#### Do Not Build a Row of Native `<input>` Elements Instead\n\nHand-rolling digit cells with native `<input type=\"text\" maxlength=\"1\">` elements duplicates focus management, paste handling, and form association that `<mds-input-otp>` already provides, and breaks Magma theming.\n\n```html\n<!-- INCORRECT -->\n<div class=\"otp-row\">\n <input type=\"text\" maxlength=\"1\">\n <input type=\"text\" maxlength=\"1\">\n <input type=\"text\" maxlength=\"1\">\n <input type=\"text\" maxlength=\"1\">\n <input type=\"text\" maxlength=\"1\">\n <input type=\"text\" maxlength=\"1\">\n</div>\n\n<!-- CORRECT -->\n<mds-input-otp name=\"otp\"></mds-input-otp>\n```\n\n#### Do Not Pierce Shadow DOM to Style Inner Cells\n\nThe inner `mds-input` cells are Shadow DOM internals. Targeting them with descendant selectors or `>>>` will break silently on any internal refactor.\n\n```css\n/* INCORRECT */\nmds-input-otp mds-input {\n --mds-input-background: red;\n}\nmds-input-otp >>> .input {\n border-radius: 0;\n}\n\n/* CORRECT - style the host layout only */\nmds-input-otp {\n gap: calc(var(--spacing) * 600);\n}\n```\n\n#### Do Not Use `autosubmit` Without a Parent `<form>`\n\n`autosubmit` calls `internals.form.requestSubmit()`. Outside a `<form>` there is no owning form, so the call is silently ignored and the expected submission never fires.\n\n```html\n<!-- INCORRECT - no owning form, submit never fires -->\n<mds-input-otp name=\"otp\" autosubmit></mds-input-otp>\n\n<!-- CORRECT - wrapped in a form that handles the submit -->\n<form action=\"/verify\" method=\"post\">\n <mds-input-otp name=\"otp\" autosubmit></mds-input-otp>\n</form>\n```\n\n#### Do Not Listen for the Native `input` or `change` Event\n\nNative DOM events may not propagate out of shadow DOM the way you expect. Read the reflected `value` attribute or use form data on submit instead.\n\n```javascript\n// INCORRECT\ndocument.querySelector('mds-input-otp').addEventListener('input', (e) => {\n console.log(e.target.value); // unreliable from outside shadow DOM\n});\n\n// CORRECT - read the reflected prop directly\nconst otpEl = document.querySelector('mds-input-otp');\ndocument.querySelector('form').addEventListener('submit', (e) => {\n e.preventDefault();\n console.log('Codice OTP:', otpEl.value);\n});\n```\n\n#### Do Not Set `length` as a Non-Integer or to Zero\n\n`length` controls how many cells are rendered. A fractional or zero value produces no cells or the wrong number. Always pass a positive integer.\n\n```html\n<!-- INCORRECT -->\n<mds-input-otp name=\"otp\" length=\"0\"></mds-input-otp>\n<mds-input-otp name=\"otp\" length=\"4.5\"></mds-input-otp>\n\n<!-- CORRECT -->\n<mds-input-otp name=\"otp\" length=\"4\"></mds-input-otp>\n```\n"
16702
16824
  },
16703
16825
  "props": [
@@ -16880,7 +17002,8 @@
16880
17002
  "mds-input-tip-item": [
16881
17003
  "mds-text"
16882
17004
  ]
16883
- }
17005
+ },
17006
+ "storybook": "form-otp--docs"
16884
17007
  },
16885
17008
  {
16886
17009
  "filePath": "src/components/mds-input-range/mds-input-range.tsx",
@@ -17199,7 +17322,8 @@
17199
17322
  "mds-input-range": [
17200
17323
  "mds-text"
17201
17324
  ]
17202
- }
17325
+ },
17326
+ "storybook": "form-range--docs"
17203
17327
  },
17204
17328
  {
17205
17329
  "filePath": "src/components/mds-input-select/mds-input-select.tsx",
@@ -17806,7 +17930,8 @@
17806
17930
  "mds-input-tip-item": [
17807
17931
  "mds-text"
17808
17932
  ]
17809
- }
17933
+ },
17934
+ "storybook": "form-select--docs"
17810
17935
  },
17811
17936
  {
17812
17937
  "filePath": "src/components/mds-input-switch/mds-input-switch.tsx",
@@ -18466,7 +18591,8 @@
18466
18591
  "mds-table-row": [
18467
18592
  "mds-input-switch"
18468
18593
  ]
18469
- }
18594
+ },
18595
+ "storybook": "form-switch--docs"
18470
18596
  },
18471
18597
  {
18472
18598
  "filePath": "src/components/mds-input-tip/mds-input-tip.tsx",
@@ -18626,7 +18752,8 @@
18626
18752
  "mds-input-select": [
18627
18753
  "mds-input-tip"
18628
18754
  ]
18629
- }
18755
+ },
18756
+ "storybook": "form-input-tip--docs"
18630
18757
  },
18631
18758
  {
18632
18759
  "filePath": "src/components/mds-input-tip-item/mds-input-tip-item.tsx",
@@ -18805,7 +18932,8 @@
18805
18932
  "mds-input-select": [
18806
18933
  "mds-input-tip-item"
18807
18934
  ]
18808
- }
18935
+ },
18936
+ "storybook": "form-input-tip-item--docs"
18809
18937
  },
18810
18938
  {
18811
18939
  "filePath": "src/components/mds-input-upload/mds-input-upload.tsx",
@@ -19235,7 +19363,8 @@
19235
19363
  "mds-badge": [
19236
19364
  "mds-text"
19237
19365
  ]
19238
- }
19366
+ },
19367
+ "storybook": "form-input-upload--docs"
19239
19368
  },
19240
19369
  {
19241
19370
  "filePath": "src/components/mds-keyboard/mds-keyboard.tsx",
@@ -19477,7 +19606,8 @@
19477
19606
  "mds-tooltip": [
19478
19607
  "mds-text"
19479
19608
  ]
19480
- }
19609
+ },
19610
+ "storybook": "ui-keyboard--docs"
19481
19611
  },
19482
19612
  {
19483
19613
  "filePath": "src/components/mds-keyboard-key/mds-keyboard-key.tsx",
@@ -19929,7 +20059,8 @@
19929
20059
  "mds-icon",
19930
20060
  "mds-text"
19931
20061
  ]
19932
- }
20062
+ },
20063
+ "storybook": "ui-keyboard-key--docs"
19933
20064
  },
19934
20065
  {
19935
20066
  "filePath": "src/components/mds-kpi/mds-kpi.tsx",
@@ -19980,7 +20111,8 @@
19980
20111
  "states": [],
19981
20112
  "dependents": [],
19982
20113
  "dependencies": [],
19983
- "dependencyGraph": {}
20114
+ "dependencyGraph": {},
20115
+ "storybook": "ui-kpi--docs"
19984
20116
  },
19985
20117
  {
19986
20118
  "filePath": "src/components/mds-kpi-item/mds-kpi-item.tsx",
@@ -20178,7 +20310,8 @@
20178
20310
  "mds-icon",
20179
20311
  "mds-text"
20180
20312
  ]
20181
- }
20313
+ },
20314
+ "storybook": "ui-kpi-kpi-item--docs"
20182
20315
  },
20183
20316
  {
20184
20317
  "filePath": "src/components/mds-label/mds-label.tsx",
@@ -20570,7 +20703,8 @@
20570
20703
  "mds-icon",
20571
20704
  "mds-text"
20572
20705
  ]
20573
- }
20706
+ },
20707
+ "storybook": "ui-label--docs"
20574
20708
  },
20575
20709
  {
20576
20710
  "filePath": "src/components/mds-link/mds-link.tsx",
@@ -20980,7 +21114,8 @@
20980
21114
  "mds-link": [
20981
21115
  "mds-icon"
20982
21116
  ]
20983
- }
21117
+ },
21118
+ "storybook": "ui-link--docs"
20984
21119
  },
20985
21120
  {
20986
21121
  "filePath": "src/components/mds-list/mds-list.tsx",
@@ -21018,7 +21153,8 @@
21018
21153
  "states": [],
21019
21154
  "dependents": [],
21020
21155
  "dependencies": [],
21021
- "dependencyGraph": {}
21156
+ "dependencyGraph": {},
21157
+ "storybook": "ui-list--docs"
21022
21158
  },
21023
21159
  {
21024
21160
  "filePath": "src/components/mds-list-item/mds-list-item.tsx",
@@ -21222,7 +21358,8 @@
21222
21358
  "mds-icon",
21223
21359
  "mds-text"
21224
21360
  ]
21225
- }
21361
+ },
21362
+ "storybook": "ui-list-list-item--docs"
21226
21363
  },
21227
21364
  {
21228
21365
  "filePath": "src/components/mds-mention/mds-mention.tsx",
@@ -21422,7 +21559,8 @@
21422
21559
  "mds-icon",
21423
21560
  "mds-text"
21424
21561
  ]
21425
- }
21562
+ },
21563
+ "storybook": "ui-mention--docs"
21426
21564
  },
21427
21565
  {
21428
21566
  "filePath": "src/components/mds-modal/mds-modal.tsx",
@@ -21465,7 +21603,7 @@
21465
21603
  }
21466
21604
  ],
21467
21605
  "usage": {
21468
- "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\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",
21606
+ "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- **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",
21469
21607
  "2. Pattern": "Correct and idiomatic ways to use the `<mds-modal>` component, ordered from most common to most specialized. Patterns 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#### Custom Window via `window` Slot\n\nSlot any element with `slot=\"window\"` to completely replace the built-in chrome (the window surface and the close button). The slotted element gets no `role` of its own: the `<dialog>` the component renders is already the dialog. Use this when a completely bespoke surface is needed - for example, a full-screen banner.\n\n```html\n<mds-modal id=\"modal-banner\" animation=\"custom\">\n <mds-banner\n slot=\"window\"\n class=\"max-w-md w-full mx-400\"\n tone=\"box\"\n deletable\n headline=\"Azione richiesta\"\n >\n <mds-text typography=\"detail\">Conferma la tua identita' per procedere.</mds-text>\n <mds-button slot=\"action\" variant=\"primary\" tone=\"text\">Annulla</mds-button>\n <mds-button slot=\"action\" variant=\"primary\" tone=\"strong\">Conferma</mds-button>\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.\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",
21470
21608
  "3. Antipattern": "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/anti-patterns.md`](../../../../agents/anti-patterns.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 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"
21471
21609
  },
@@ -21993,7 +22131,8 @@
21993
22131
  "mds-status-bar": [
21994
22132
  "mds-modal"
21995
22133
  ]
21996
- }
22134
+ },
22135
+ "storybook": "ui-modal--docs"
21997
22136
  },
21998
22137
  {
21999
22138
  "filePath": "src/components/mds-note/mds-note.tsx",
@@ -22219,7 +22358,8 @@
22219
22358
  "mds-icon",
22220
22359
  "mds-text"
22221
22360
  ]
22222
- }
22361
+ },
22362
+ "storybook": "ui-note--docs"
22223
22363
  },
22224
22364
  {
22225
22365
  "filePath": "src/components/mds-notification/mds-notification.tsx",
@@ -22485,7 +22625,8 @@
22485
22625
  "mds-notification": [
22486
22626
  "mds-text"
22487
22627
  ]
22488
- }
22628
+ },
22629
+ "storybook": "ui-notification--docs"
22489
22630
  },
22490
22631
  {
22491
22632
  "filePath": "src/components/mds-paginator/mds-paginator.tsx",
@@ -22618,7 +22759,8 @@
22618
22759
  "mds-icon",
22619
22760
  "mds-text"
22620
22761
  ]
22621
- }
22762
+ },
22763
+ "storybook": "ui-paginator--docs"
22622
22764
  },
22623
22765
  {
22624
22766
  "filePath": "src/components/mds-paginator-item/mds-paginator-item.tsx",
@@ -22833,7 +22975,8 @@
22833
22975
  "mds-paginator": [
22834
22976
  "mds-paginator-item"
22835
22977
  ]
22836
- }
22978
+ },
22979
+ "storybook": "ui-paginator-item--docs"
22837
22980
  },
22838
22981
  {
22839
22982
  "filePath": "src/components/mds-policy-ai/mds-policy-ai.tsx",
@@ -23080,7 +23223,8 @@
23080
23223
  "mds-text",
23081
23224
  "mds-button"
23082
23225
  ]
23083
- }
23226
+ },
23227
+ "storybook": "ui-policy-ai--docs"
23084
23228
  },
23085
23229
  {
23086
23230
  "filePath": "src/components/mds-pref/mds-pref.tsx",
@@ -23220,7 +23364,8 @@
23220
23364
  "mds-pref": [
23221
23365
  "mds-text"
23222
23366
  ]
23223
- }
23367
+ },
23368
+ "storybook": "ui-preferences--docs"
23224
23369
  },
23225
23370
  {
23226
23371
  "filePath": "src/components/mds-pref-animation/mds-pref-animation.tsx",
@@ -23370,7 +23515,8 @@
23370
23515
  "mds-icon",
23371
23516
  "mds-text"
23372
23517
  ]
23373
- }
23518
+ },
23519
+ "storybook": "ui-preferences-animation--docs"
23374
23520
  },
23375
23521
  {
23376
23522
  "filePath": "src/components/mds-pref-consumption/mds-pref-consumption.tsx",
@@ -23520,7 +23666,8 @@
23520
23666
  "mds-icon",
23521
23667
  "mds-text"
23522
23668
  ]
23523
- }
23669
+ },
23670
+ "storybook": "ui-preferences-consumption--docs"
23524
23671
  },
23525
23672
  {
23526
23673
  "filePath": "src/components/mds-pref-contrast/mds-pref-contrast.tsx",
@@ -23670,7 +23817,8 @@
23670
23817
  "mds-icon",
23671
23818
  "mds-text"
23672
23819
  ]
23673
- }
23820
+ },
23821
+ "storybook": "ui-preferences-contrast--docs"
23674
23822
  },
23675
23823
  {
23676
23824
  "filePath": "src/components/mds-pref-language/mds-pref-language.tsx",
@@ -23849,7 +23997,8 @@
23849
23997
  "mds-icon",
23850
23998
  "mds-text"
23851
23999
  ]
23852
- }
24000
+ },
24001
+ "storybook": "ui-preferences-language--docs"
23853
24002
  },
23854
24003
  {
23855
24004
  "filePath": "src/components/mds-pref-language-item/mds-pref-language-item.tsx",
@@ -23972,7 +24121,8 @@
23972
24121
  "mds-icon",
23973
24122
  "mds-text"
23974
24123
  ]
23975
- }
24124
+ },
24125
+ "storybook": "ui-preferences-language-item--docs"
23976
24126
  },
23977
24127
  {
23978
24128
  "filePath": "src/components/mds-pref-mode/mds-pref-mode.tsx",
@@ -24228,7 +24378,8 @@
24228
24378
  "mds-icon",
24229
24379
  "mds-text"
24230
24380
  ]
24231
- }
24381
+ },
24382
+ "storybook": "ui-preferences-mode--docs"
24232
24383
  },
24233
24384
  {
24234
24385
  "filePath": "src/components/mds-pref-theme/mds-pref-theme.tsx",
@@ -24510,7 +24661,8 @@
24510
24661
  "mds-icon",
24511
24662
  "mds-text"
24512
24663
  ]
24513
- }
24664
+ },
24665
+ "storybook": "ui-preferences-theme--docs"
24514
24666
  },
24515
24667
  {
24516
24668
  "filePath": "src/components/mds-pref-theme-item/mds-pref-theme-item.tsx",
@@ -24743,7 +24895,8 @@
24743
24895
  "mds-icon",
24744
24896
  "mds-text"
24745
24897
  ]
24746
- }
24898
+ },
24899
+ "storybook": "ui-preferences-theme-item--docs"
24747
24900
  },
24748
24901
  {
24749
24902
  "filePath": "src/components/mds-price-table/mds-price-table.tsx",
@@ -24781,7 +24934,8 @@
24781
24934
  "states": [],
24782
24935
  "dependents": [],
24783
24936
  "dependencies": [],
24784
- "dependencyGraph": {}
24937
+ "dependencyGraph": {},
24938
+ "storybook": "ui-price-table--docs"
24785
24939
  },
24786
24940
  {
24787
24941
  "filePath": "src/components/mds-price-table-features/mds-price-table-features.tsx",
@@ -24874,7 +25028,8 @@
24874
25028
  "mds-price-table-features": [
24875
25029
  "mds-text"
24876
25030
  ]
24877
- }
25031
+ },
25032
+ "storybook": "ui-price-table-price-table-features--docs"
24878
25033
  },
24879
25034
  {
24880
25035
  "filePath": "src/components/mds-price-table-features-cell/mds-price-table-features-cell.tsx",
@@ -25029,7 +25184,8 @@
25029
25184
  "mds-price-table-features-cell": [
25030
25185
  "mds-text"
25031
25186
  ]
25032
- }
25187
+ },
25188
+ "storybook": "ui-price-table-price-table-features-cell--docs"
25033
25189
  },
25034
25190
  {
25035
25191
  "filePath": "src/components/mds-price-table-features-row/mds-price-table-features-row.tsx",
@@ -25092,7 +25248,8 @@
25092
25248
  "states": [],
25093
25249
  "dependents": [],
25094
25250
  "dependencies": [],
25095
- "dependencyGraph": {}
25251
+ "dependencyGraph": {},
25252
+ "storybook": "ui-price-table-price-table-features-row--docs"
25096
25253
  },
25097
25254
  {
25098
25255
  "filePath": "src/components/mds-price-table-header/mds-price-table-header.tsx",
@@ -25130,7 +25287,8 @@
25130
25287
  "states": [],
25131
25288
  "dependents": [],
25132
25289
  "dependencies": [],
25133
- "dependencyGraph": {}
25290
+ "dependencyGraph": {},
25291
+ "storybook": "ui-price-table-price-table-header--docs"
25134
25292
  },
25135
25293
  {
25136
25294
  "filePath": "src/components/mds-price-table-list/mds-price-table-list.tsx",
@@ -25230,7 +25388,8 @@
25230
25388
  "mds-price-table-list": [
25231
25389
  "mds-separator"
25232
25390
  ]
25233
- }
25391
+ },
25392
+ "storybook": "ui-price-table-price-table-list--docs"
25234
25393
  },
25235
25394
  {
25236
25395
  "filePath": "src/components/mds-price-table-list-item/mds-price-table-list-item.tsx",
@@ -25377,7 +25536,8 @@
25377
25536
  "mds-price-table-list-item": [
25378
25537
  "mds-text"
25379
25538
  ]
25380
- }
25539
+ },
25540
+ "storybook": "ui-price-table-price-table-list-item--docs"
25381
25541
  },
25382
25542
  {
25383
25543
  "filePath": "src/components/mds-progress/mds-progress.tsx",
@@ -25752,7 +25912,8 @@
25752
25912
  "mds-stepper-bar-item": [
25753
25913
  "mds-progress"
25754
25914
  ]
25755
- }
25915
+ },
25916
+ "storybook": "ui-progress--docs"
25756
25917
  },
25757
25918
  {
25758
25919
  "filePath": "src/components/mds-push-notification/mds-push-notification.tsx",
@@ -25775,8 +25936,8 @@
25775
25936
  }
25776
25937
  ],
25777
25938
  "usage": {
25778
- "1. Description": "The `<mds-push-notification>` web component is the Magma Design System container that hosts and orchestrates a stack of transient notification items, managing their show/hide lifecycle, entry/exit animations, and overall visibility. It is a compound parent: its default slot holds `mds-push-notification-item` children, and it has no direct HTML primitive equivalent.\n\n#### Semantic Behavior\n\n- **Slot-driven lifecycle**: Items placed in the default slot are animated in automatically; each item animates out and is removed when closed (an item shows its close button only with `deletable`).\n- **Built-in clear button**: The container always renders its own clear button, labelled in the page language (\"Clear notifications\", \"Cancella notifiche\"), which animates out every item and hides the container.\n- **Auto vs. manual behavior**: With `behavior=\"auto\"` the container shows itself as soon as one or more items are added; with `behavior=\"manual\"` visibility is driven only by the `visible` prop or the imperative methods.\n- **Empty-stack auto-hide**: When the last remaining item animates out, the container hides itself regardless of behavior; the clear button and `hide()` hide it too.\n- **Emitted events**: `mdsPushNotificationShow` fires when it becomes visible, `mdsPushNotificationHide` when hidden, and `mdsPushNotificationChange` on every transition carrying a `{ visible: boolean }` detail.\n- **Imperative API**: Exposes `show()` and `hide()` methods to control visibility programmatically, plus `removeNotification()` to dismiss one or an array of `mds-push-notification-item` elements with the standard outro animation.\n- **Animation timing**: The intro and outro motion of the items is set by the component; the fade-out delay and the gap between items are read from the public CSS custom properties `--mds-push-notification-fadeout-delay` and `--mds-push-notification-gap`, so they are themeable without code changes.\n\n#### Properties & Visual Configurations\n\nThe container intentionally exposes a minimal prop surface; most configuration is structural (which items you slot in) or stylistic (via CSS custom properties).\n\n#### Other behavioral props\n\n- **`behavior`** selects the visibility strategy: pick `'auto'` (default) when the stack should appear and disappear purely as a function of how many items it contains, and `'manual'` when you want explicit control over when the container is shown via `visible` or the `show()`/`hide()` methods.\n- **`visible`** is the controlled visibility flag; set it to drive the container open or closed, while reading it returns the current visibility.\n",
25779
- "2. Pattern": "Correct and idiomatic ways to use the `<mds-push-notification>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Minimal Auto-Managed Stack\n\nThe default `behavior=\"auto\"` configuration. Drop `mds-push-notification-item` children into the default slot and the container shows itself, animates each item in, and hides itself when all items have been dismissed. Set `deletable` on an item to give it its own close button.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n deletable\n subject=\"Nuovo messaggio\"\n message=\"Il documento e' pronto per la revisione.\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Items with Avatar Preview\n\nUse `preview=\"avatar\"` and `src` to show a user photo. Supply `initials` as a fallback when no image is available.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n preview=\"avatar\"\n src=\"/avatars/marco.jpg\"\n initials=\"MC\"\n subject=\"Marco Cicognetti\"\n message=\"Ci sei andato poi alla riunione?\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Items with Icon Preview\n\nUse `icon` (an icon slug with its set prefix) instead of `src` when the notification represents an event or system action rather than a person.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/attachment\"\n subject=\"Documento allegato\"\n message=\"E' stato caricato un nuovo allegato nella pratica 2024-1042.\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Item with Date and Timestamp\n\nPass an ISO 8601 datetime string to display a relative time-ago label (default) or a static formatted date.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n subject=\"Approvazione completata\"\n message=\"La richiesta e' stata approvata.\"\n datetime=\"2024-11-12T09:30:00Z\"\n ></mds-push-notification-item>\n\n <!-- Static date format -->\n <mds-push-notification-item\n subject=\"Scadenza contratto\"\n message=\"Il contratto scade il giorno indicato.\"\n datetime=\"2024-12-31T00:00:00Z\"\n date-format=\"DD/MM/YYYY\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Item with Action Button\n\nSlot an `mds-button` into the `action` slot of the item to provide an inline CTA.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n preview=\"avatar\"\n src=\"/avatars/sara.jpg\"\n subject=\"Sara Ho\"\n message=\"Hai ricevuto una nuova richiesta di collaborazione.\"\n >\n <mds-button slot=\"action\" variant=\"primary\" tone=\"weak\" size=\"sm\">\n Rispondi\n </mds-button>\n </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Manual Behavior with Programmatic Control\n\nSet `behavior=\"manual\"` when visibility should be controlled by your application logic rather than inferred from slot contents. Toggle the `visible` attribute or call `show()` / `hide()` on the element.\n\n```html\n<mds-push-notification behavior=\"manual\" id=\"notif-panel\">\n <mds-push-notification-item\n subject=\"Aggiornamento sistema\"\n message=\"Un aggiornamento e' disponibile. Riavviare per applicarlo.\"\n ></mds-push-notification-item>\n</mds-push-notification>\n\n<script>\n const panel = document.querySelector('#notif-panel');\n\n // Show programmatically\n panel.show();\n\n // Hide programmatically\n panel.hide();\n</script>\n```\n\n#### Programmatic Dismissal of a Single Item\n\nCall `removeNotification()` with an `mds-push-notification-item` element reference to animate it out and remove it without the user interacting with the close button.\n\n```html\n<mds-push-notification id=\"notif-panel\">\n <mds-push-notification-item id=\"item-1\"\n subject=\"Avviso temporaneo\"\n message=\"Questa notifica viene rimossa dopo 5 secondi.\"\n ></mds-push-notification-item>\n</mds-push-notification>\n\n<script>\n const panel = document.querySelector('#notif-panel');\n const item = document.querySelector('#item-1');\n\n setTimeout(() => {\n panel.removeNotification(item);\n }, 5000);\n</script>\n```\n\n#### Reacting to Visibility Events\n\nListen to `mdsPushNotificationShow`, `mdsPushNotificationHide`, or `mdsPushNotificationChange` to synchronize UI state when the panel opens or closes.\n\n```javascript\nconst panel = document.querySelector('mds-push-notification');\n\npanel.addEventListener('mdsPushNotificationShow', () => {\n console.info('Pannello notifiche aperto');\n});\n\npanel.addEventListener('mdsPushNotificationHide', () => {\n console.info('Pannello notifiche chiuso');\n});\n\npanel.addEventListener('mdsPushNotificationChange', (e) => {\n console.info('Visibilita cambiata:', e.detail.visible);\n});\n```\n\n#### Item Tone and Variant\n\nUse `variant` and `tone` on the item to reflect the semantic nature of the notification (status or theme family). `tone` accepts `strong` or `weak` on this component. They paint the item's icon or avatar preview, so they show only together with `icon` (or `preview=\"avatar\"`).\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/check-circle\"\n variant=\"success\"\n tone=\"weak\"\n subject=\"Operazione completata\"\n message=\"Il file e' stato salvato con successo.\"\n ></mds-push-notification-item>\n\n <mds-push-notification-item\n icon=\"mi/baseline/error\"\n variant=\"error\"\n tone=\"strong\"\n subject=\"Errore critico\"\n message=\"Impossibile completare l'operazione. Riprovare.\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nOverride the fade-out delay, the gap between items, and the panel background through the public `--mds-push-notification-*` properties; the intro and outro motion of the items is set by the component. Set them on the host or a parent selector; for colours name a semantic role, `rgb(var(--magma-<role>))` ([`agents/color.md`](../../../../agents/color.md)).\n\n```css\nmds-push-notification {\n --mds-push-notification-gap: calc(var(--spacing) * 300);\n --mds-push-notification-fadeout-delay: 0.5s;\n --mds-push-notification-background: linear-gradient(\n to right,\n rgb(var(--magma-surface-overlay) / 0) 0%,\n rgb(var(--magma-surface-overlay) / 0.95) 100%\n );\n}\n```\n",
25939
+ "1. Description": "The `<mds-push-notification>` web component is the Magma Design System container that hosts and orchestrates a stack of transient notification items, managing their show/hide lifecycle, entry/exit animations, and overall visibility. It is a compound parent: its default slot holds `mds-push-notification-item` children, and it has no direct HTML primitive equivalent.\n\n#### Semantic Behavior\n\n- **Slot-driven lifecycle**: Items placed in the default slot are animated in automatically; each item animates out and is removed when closed (an item shows its close button only with `dismissible`).\n- **Built-in clear button**: The container always renders its own clear button, labelled in the page language (\"Clear notifications\", \"Cancella notifiche\"), which animates out every item and hides the container.\n- **Auto vs. manual behavior**: With `behavior=\"auto\"` the container shows itself as soon as one or more items are added; with `behavior=\"manual\"` visibility is driven only by the `visible` prop or the imperative methods.\n- **Empty-stack auto-hide**: When the last remaining item animates out, the container hides itself regardless of behavior; the clear button and `hide()` hide it too.\n- **Emitted events**: `mdsPushNotificationShow` fires when it becomes visible, `mdsPushNotificationHide` when hidden, and `mdsPushNotificationChange` on every transition carrying a `{ visible: boolean }` detail.\n- **Imperative API**: Exposes `show()` and `hide()` methods to control visibility programmatically, plus `removeNotification()` to dismiss one or an array of `mds-push-notification-item` elements with the standard outro animation.\n- **Animation timing**: The intro and outro motion of the items is set by the component; the fade-out delay and the gap between items are read from the public CSS custom properties `--mds-push-notification-fadeout-delay` and `--mds-push-notification-gap`, so they are themeable without code changes.\n\n#### Properties & Visual Configurations\n\nThe container intentionally exposes a minimal prop surface; most configuration is structural (which items you slot in) or stylistic (via CSS custom properties).\n\n#### Other behavioral props\n\n- **`behavior`** selects the visibility strategy: pick `'auto'` (default) when the stack should appear and disappear purely as a function of how many items it contains, and `'manual'` when you want explicit control over when the container is shown via `visible` or the `show()`/`hide()` methods.\n- **`visible`** is the controlled visibility flag; set it to drive the container open or closed, while reading it returns the current visibility.\n",
25940
+ "2. Pattern": "Correct and idiomatic ways to use the `<mds-push-notification>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Minimal Auto-Managed Stack\n\nThe default `behavior=\"auto\"` configuration. Drop `mds-push-notification-item` children into the default slot and the container shows itself, animates each item in, and hides itself when all items have been dismissed. Set `dismissible` on an item to give it its own close button.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n dismissible\n subject=\"Nuovo messaggio\"\n message=\"Il documento e' pronto per la revisione.\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Items with Avatar Preview\n\nUse `preview=\"avatar\"` and `src` to show a user photo. Supply `initials` as a fallback when no image is available.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n preview=\"avatar\"\n src=\"/avatars/marco.jpg\"\n initials=\"MC\"\n subject=\"Marco Cicognetti\"\n message=\"Ci sei andato poi alla riunione?\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Items with Icon Preview\n\nUse `icon` (an icon slug with its set prefix) instead of `src` when the notification represents an event or system action rather than a person.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/attachment\"\n subject=\"Documento allegato\"\n message=\"E' stato caricato un nuovo allegato nella pratica 2024-1042.\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Item with Date and Timestamp\n\nPass an ISO 8601 datetime string to display a relative time-ago label (default) or a static formatted date.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n subject=\"Approvazione completata\"\n message=\"La richiesta e' stata approvata.\"\n datetime=\"2024-11-12T09:30:00Z\"\n ></mds-push-notification-item>\n\n <!-- Static date format -->\n <mds-push-notification-item\n subject=\"Scadenza contratto\"\n message=\"Il contratto scade il giorno indicato.\"\n datetime=\"2024-12-31T00:00:00Z\"\n date-format=\"DD/MM/YYYY\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Item with Action Button\n\nSlot an `mds-button` into the `action` slot of the item to provide an inline CTA.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n preview=\"avatar\"\n src=\"/avatars/sara.jpg\"\n subject=\"Sara Ho\"\n message=\"Hai ricevuto una nuova richiesta di collaborazione.\"\n >\n <mds-button slot=\"action\" variant=\"primary\" tone=\"weak\" size=\"sm\">\n Rispondi\n </mds-button>\n </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Manual Behavior with Programmatic Control\n\nSet `behavior=\"manual\"` when visibility should be controlled by your application logic rather than inferred from slot contents. Toggle the `visible` attribute or call `show()` / `hide()` on the element.\n\n```html\n<mds-push-notification behavior=\"manual\" id=\"notif-panel\">\n <mds-push-notification-item\n subject=\"Aggiornamento sistema\"\n message=\"Un aggiornamento e' disponibile. Riavviare per applicarlo.\"\n ></mds-push-notification-item>\n</mds-push-notification>\n\n<script>\n const panel = document.querySelector('#notif-panel');\n\n // Show programmatically\n panel.show();\n\n // Hide programmatically\n panel.hide();\n</script>\n```\n\n#### Programmatic Dismissal of a Single Item\n\nCall `removeNotification()` with an `mds-push-notification-item` element reference to animate it out and remove it without the user interacting with the close button.\n\n```html\n<mds-push-notification id=\"notif-panel\">\n <mds-push-notification-item id=\"item-1\"\n subject=\"Avviso temporaneo\"\n message=\"Questa notifica viene rimossa dopo 5 secondi.\"\n ></mds-push-notification-item>\n</mds-push-notification>\n\n<script>\n const panel = document.querySelector('#notif-panel');\n const item = document.querySelector('#item-1');\n\n setTimeout(() => {\n panel.removeNotification(item);\n }, 5000);\n</script>\n```\n\n#### Reacting to Visibility Events\n\nListen to `mdsPushNotificationShow`, `mdsPushNotificationHide`, or `mdsPushNotificationChange` to synchronize UI state when the panel opens or closes.\n\n```javascript\nconst panel = document.querySelector('mds-push-notification');\n\npanel.addEventListener('mdsPushNotificationShow', () => {\n console.info('Pannello notifiche aperto');\n});\n\npanel.addEventListener('mdsPushNotificationHide', () => {\n console.info('Pannello notifiche chiuso');\n});\n\npanel.addEventListener('mdsPushNotificationChange', (e) => {\n console.info('Visibilita cambiata:', e.detail.visible);\n});\n```\n\n#### Item Tone and Variant\n\nUse `variant` and `tone` on the item to reflect the semantic nature of the notification (status or theme family). `tone` accepts `strong` or `weak` on this component. They paint the item's icon or avatar preview, so they show only together with `icon` (or `preview=\"avatar\"`).\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/check-circle\"\n variant=\"success\"\n tone=\"weak\"\n subject=\"Operazione completata\"\n message=\"Il file e' stato salvato con successo.\"\n ></mds-push-notification-item>\n\n <mds-push-notification-item\n icon=\"mi/baseline/error\"\n variant=\"error\"\n tone=\"strong\"\n subject=\"Errore critico\"\n message=\"Impossibile completare l'operazione. Riprovare.\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nOverride the fade-out delay, the gap between items, and the panel background through the public `--mds-push-notification-*` properties; the intro and outro motion of the items is set by the component. Set them on the host or a parent selector; for colours name a semantic role, `rgb(var(--magma-<role>))` ([`agents/color.md`](../../../../agents/color.md)).\n\n```css\nmds-push-notification {\n --mds-push-notification-gap: calc(var(--spacing) * 300);\n --mds-push-notification-fadeout-delay: 0.5s;\n --mds-push-notification-background: linear-gradient(\n to right,\n rgb(var(--magma-surface-overlay) / 0) 0%,\n rgb(var(--magma-surface-overlay) / 0.95) 100%\n );\n}\n```\n",
25780
25941
  "3. Antipattern": "Common incorrect uses of `<mds-push-notification>`. 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/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Put Arbitrary HTML in the Default Slot\n\nThe default slot is designed for `mds-push-notification-item` children only. Placing raw HTML or other components breaks the animation lifecycle, event wiring, and the intro/outro sequencing the container manages.\n\n```html\n<!-- INCORRECT -->\n<mds-push-notification>\n <div class=\"my-notification\">\n <strong>Avviso</strong>\n <p>Il documento e' pronto.</p>\n </div>\n</mds-push-notification>\n\n<!-- CORRECT -->\n<mds-push-notification>\n <mds-push-notification-item\n subject=\"Avviso\"\n message=\"Il documento e' pronto.\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Do Not Set `visible=\"false\"` to Hide the Panel\n\n`visible` is a boolean prop: a false boolean is written by removing the attribute, the convention for every Magma boolean ([`agents/conventions.md`](../../../../agents/conventions.md)). Stencil does parse `\"false\"` as `false`, but the attribute stays in the markup until the component hydrates and its reflection removes it, so a `[visible]` selector or any code reading the attribute sees it set in the meantime. Remove the attribute entirely - or call `hide()` - to close the panel.\n\n```html\n<!-- INCORRECT -->\n<mds-push-notification visible=\"false\"></mds-push-notification>\n\n<!-- CORRECT: remove the attribute -->\n<mds-push-notification></mds-push-notification>\n```\n\n```javascript\n// CORRECT: via imperative method\ndocument.querySelector('mds-push-notification').hide();\n```\n\n#### Do Not Listen to the Native `close` Event Instead of `mdsPushNotificationHide`\n\nThe component emits `mdsPushNotificationHide` when the panel hides. Listening for a native `close` event will never fire because the component does not dispatch it, and native DOM events from inside the shadow root do not reliably bubble to the light DOM.\n\n```javascript\n// INCORRECT\npanel.addEventListener('close', () => updateUI());\n\n// CORRECT\npanel.addEventListener('mdsPushNotificationHide', () => updateUI());\n```\n\n#### Do Not Use `behavior=\"manual\"` and Then Forget to Call `show()` / `hide()`\n\nWith `behavior=\"manual\"` the container never auto-shows when items are added; you must explicitly call `show()` or set `visible`. Leaving it on `manual` without wiring visibility logic means notifications are silently queued but never displayed.\n\n```html\n<!-- INCORRECT: items never appear because manual mode needs explicit show() -->\n<mds-push-notification behavior=\"manual\" id=\"notif-panel\">\n <mds-push-notification-item\n subject=\"Nuovo messaggio\"\n message=\"Messaggio ricevuto.\"\n ></mds-push-notification-item>\n</mds-push-notification>\n\n<!-- CORRECT: call show() after adding items -->\n<mds-push-notification behavior=\"manual\" id=\"notif-panel\">\n <mds-push-notification-item\n subject=\"Nuovo messaggio\"\n message=\"Messaggio ricevuto.\"\n ></mds-push-notification-item>\n</mds-push-notification>\n\n<script>\n document.querySelector('#notif-panel').show();\n</script>\n```\n\n#### Do Not Pierce Shadow DOM to Style Item Internals\n\nThe only supported customization surface for the container is the public `--mds-push-notification-*` CSS custom properties plus the documented `::part(notifications)` part. Use the public per-item CSS custom properties (prefixed `--mds-push-notification-item-*`) for item-level styling. Do not reach into shadow parts that are not documented.\n\n```css\n/* INCORRECT */\nmds-push-notification >>> .notifications {\n background: white;\n}\nmds-push-notification::part(content) {\n padding: 2rem;\n}\n\n/* CORRECT */\nmds-push-notification {\n --mds-push-notification-background: rgb(var(--magma-surface-overlay) / 0.9);\n --mds-push-notification-gap: calc(var(--spacing) * 300);\n}\nmds-push-notification::part(notifications) {\n /* documented part - safe to target */\n padding-block: calc(var(--spacing) * 200);\n}\n```\n\n#### Do Not Slot Actions in the Wrong Slot\n\nAction buttons belong in the `action` slot of `mds-push-notification-item`, not in the default slot of `mds-push-notification`. Placing a button in the parent's default slot treats it like a notification item, breaks the animation sequence, and the button will be styled and animated as if it were a notification. A clear-all button is not needed either: the container renders its own.\n\n```html\n<!-- INCORRECT: button lands in the parent's default slot -->\n<mds-push-notification>\n <mds-button variant=\"dark\">Cancella tutto</mds-button>\n <mds-push-notification-item subject=\"Avviso\" message=\"Nuovo messaggio.\"></mds-push-notification-item>\n</mds-push-notification>\n\n<!-- CORRECT: action belongs on the item's action slot -->\n<mds-push-notification>\n <mds-push-notification-item subject=\"Avviso\" message=\"Nuovo messaggio.\">\n <mds-button slot=\"action\" variant=\"primary\" tone=\"weak\" size=\"sm\">Apri</mds-button>\n </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Do Not Apply an Unsupported `tone` Value to Item\n\n`mds-push-notification-item` accepts `tone=\"strong\"` or `tone=\"weak\"` only (`ToneMinimalVariantType`). Using `tone=\"outline\"` (a tone of `mds-button` and `mds-badge`) silently falls back to the default `weak` look and the intended visual emphasis is lost. `variant` and `tone` paint only the item's icon or avatar, so pair them with `icon`.\n\n```html\n<!-- INCORRECT: outline and text are not supported tones for this component -->\n<mds-push-notification-item\n icon=\"mi/baseline/error\"\n variant=\"error\"\n tone=\"outline\"\n subject=\"Errore\"\n message=\"Operazione fallita.\"\n></mds-push-notification-item>\n\n<!-- CORRECT -->\n<mds-push-notification-item\n icon=\"mi/baseline/error\"\n variant=\"error\"\n tone=\"strong\"\n subject=\"Errore\"\n message=\"Operazione fallita.\"\n></mds-push-notification-item>\n```\n"
25781
25942
  },
25782
25943
  "props": [
@@ -26061,7 +26222,8 @@
26061
26222
  "mds-icon",
26062
26223
  "mds-text"
26063
26224
  ]
26064
- }
26225
+ },
26226
+ "storybook": "ui-push-notification--docs"
26065
26227
  },
26066
26228
  {
26067
26229
  "filePath": "src/components/mds-push-notification-item/mds-push-notification-item.tsx",
@@ -26100,8 +26262,8 @@
26100
26262
  }
26101
26263
  ],
26102
26264
  "usage": {
26103
- "1. Description": "The `<mds-push-notification-item>` web component is a single notification card rendered inside its parent container [`<mds-push-notification>`](../mds-push-notification/AGENTS.md). It composes an avatar/image, a subject, a relative or formatted timestamp, a message body and an optional dismiss control into one toast-like row.\n\n#### Semantic Behavior\n\n- **Compound child only**: It must be placed as a direct default-slot child of `<mds-push-notification>`; it is not used standalone or mixed with other child types, since the parent animates intro/outro and manages stacking.\n- **Dismiss reports up, removal happens in the parent**: Clicking the built-in close button emits the bubbling `mdsPushNotificationItemClose` event, with the `id` of the item as `detail.id`; the parent runs the outro animation and removes the item. The item never removes itself.\n- **Parent-driven visibility lifecycle**: When the last item closes, the parent auto-hides the whole notification area.\n- **Timestamp rendering**: With `dateFormat=\"timeago\"` `datetime` shows a localized relative time (\"2 minutes ago\"); otherwise the value is treated as a date-format string for a static date.\n- **Localization**: The relative-time strings and the dismiss button title are localized (el/en/es/it).\n- **Conditional avatar vs. picture**: An `<mds-avatar>` is rendered when `icon` is set or `preview=\"avatar\"`; when `src` is set and `preview` is not `avatar`, an `<mds-img>` picture is rendered (next to the avatar when `icon` is also set).\n- **Slot detection**: The `badge` and `action` named slot wrappers stay hidden (`display: none`) until matching slotted children exist, so empty slots take no space.\n\n#### Properties & Visual Configurations\n\n- **`deletable`** (default `false`): Controls whether the dismiss button is shown. Add it to let the user close the notification manually; leave it off for items the user should not close.\n- **`preview`**: Pick `avatar` to show the `src` image (or `initials`/`icon` fallback) as a compact round avatar, or `image` (default) to show `src` as a larger inline picture preview.\n- **`initials`**: Provided as the avatar fallback when no image is available; it overrides `tone`/`variant` styling so the user stays visually recognizable.\n- **`dateFormat`**: Use `timeago` for a live relative timestamp, or any date-format token string for a fixed display date.\n\nFor `tone` and `variant`, this component consumes the shared color ladders defined in [`agents/variants.md`](../../../../agents/variants.md); the values are forwarded to the underlying `<mds-avatar>` and follow the avatar tone/variant set rather than adding component-specific values.\n",
26104
- "2. Pattern": "Correct and idiomatic ways to use the `<mds-push-notification-item>` component, ordered from most common to most specialized. Patterns 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 Message Notification\n\nThe minimal form: a message body with an icon and a relative timestamp. Always nest the item inside [`mds-push-notification`](../mds-push-notification/AGENTS.md), which manages stacking and animation.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/email\"\n subject=\"Nuovo messaggio\"\n message=\"Hai ricevuto 3 nuovi messaggi da account diversi\"\n datetime=\"2024-06-01T10:30:00\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Variant for Semantic Status\n\nUse `variant` to communicate meaning - success, warning, error, info - and `tone` to set visual weight. The values are forwarded to the internal `<mds-avatar>`.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/check-circle\"\n subject=\"Salvataggio completato\"\n message=\"Il documento e' stato salvato con successo\"\n datetime=\"2024-06-01T10:31:00\"\n variant=\"success\"\n tone=\"strong\"\n ></mds-push-notification-item>\n\n <mds-push-notification-item\n icon=\"mi/baseline/warning\"\n subject=\"Attenzione\"\n message=\"La sessione scadra' tra 5 minuti\"\n datetime=\"2024-06-01T10:32:00\"\n variant=\"warning\"\n tone=\"weak\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Dismissable Notification\n\nAdd the `deletable` attribute to show the dismiss button, letting the user close the notification manually. Without it the notification cannot be dismissed by the user - keep it off for system notifications the user must not close.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n deletable\n icon=\"mi/baseline/email\"\n subject=\"Nuovo messaggio\"\n message=\"Hai ricevuto un nuovo messaggio\"\n datetime=\"2024-06-01T09:00:00\"\n variant=\"info\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Action Buttons via the `action` Slot\n\nSlot one or more `<mds-button>` elements into `slot=\"action\"` for in-notification CTAs. Use `size=\"sm\"` to keep the actions compact.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/person\"\n subject=\"Mario Giannini\"\n message=\"Ciao, sono Mario, questo e' il mio contatto, buona giornata!\"\n datetime=\"2024-06-01T10:25:00\"\n variant=\"primary\"\n tone=\"strong\"\n >\n <mds-button slot=\"action\" variant=\"success\" tone=\"weak\" size=\"sm\" label=\"Accetta\"></mds-button>\n <mds-button slot=\"action\" variant=\"error\" tone=\"weak\" size=\"sm\" label=\"Ignora\"></mds-button>\n </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Badge Label via the `badge` Slot\n\nSlot an `<mds-badge>` into `slot=\"badge\"` to show a category or type label above the subject line.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/attach-file\"\n subject=\"Nuovo allegato\"\n message=\"Hai ricevuto un nuovo file allegato da Luca Bianchi\"\n datetime=\"2024-06-01T10:20:00\"\n variant=\"primary\"\n >\n <mds-badge slot=\"badge\" variant=\"amaranth\" tone=\"weak\" label=\"pdf\"></mds-badge>\n <mds-button slot=\"action\" tone=\"outline\" size=\"sm\" label=\"Scarica\"></mds-button>\n </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Avatar Mode with Image\n\nSet `src` and `preview=\"avatar\"` to display a user photo as a round avatar instead of the default full-width image preview.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n src=\"./avatar-sarah.jpeg\"\n preview=\"avatar\"\n subject=\"Sarah Ho\"\n message=\"Ciao, sono Sarah, questo e' il mio contatto, buona giornata!\"\n datetime=\"2024-06-01T10:15:00\"\n variant=\"primary\"\n tone=\"strong\"\n >\n <mds-button slot=\"action\" variant=\"success\" tone=\"weak\" size=\"sm\" label=\"Scrivi\"></mds-button>\n </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Avatar Mode with Initials Fallback\n\nWhen no image is available, set `initials` and `preview=\"avatar\"`. The initials override `tone` and `variant` coloring so the user stays visually distinguishable.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n initials=\"MG\"\n preview=\"avatar\"\n subject=\"Mario Giannini\"\n message=\"Ha modificato il documento condiviso\"\n datetime=\"2024-06-01T10:10:00\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Inline Image Preview\n\nOmit `preview=\"avatar\"` (or keep the default `image`) and supply `src` to show the image as a larger inline thumbnail - useful for file or media notifications.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n src=\"./book-cover-01.webp\"\n subject=\"Anteprima immagine\"\n message=\"La copertina e' stata aggiornata\"\n datetime=\"2024-06-01T10:05:00\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Fixed Date Format\n\nUse any `dayjs`-compatible format string as `date-format` to show a static date instead of the default relative \"time ago\" display.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/event\"\n subject=\"Promemoria riunione\"\n message=\"La riunione di progetto e' fissata per domani\"\n datetime=\"2024-06-01T09:00:00\"\n date-format=\"DD/MM/YYYY\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Listening to the Dismiss Event\n\nListen to `mdsPushNotificationItemClose` to handle cleanup when the user dismisses the item. The parent `<mds-push-notification>` does this automatically, but you can also add your own logic (e.g. marking the notification read in the server). The event carries the `id` of the item in `detail.id`.\n\n```javascript\ndocument\n .querySelector('mds-push-notification-item')\n .addEventListener('mdsPushNotificationItemClose', (event) => {\n markNotificationRead(event.detail.id);\n });\n```\n\n#### Styling Customization\n\nCustomize the item only through its public `--mds-push-notification-item-*` CSS custom properties.\n\n```css\n.app-notifications mds-push-notification-item {\n --mds-push-notification-item-shadow: var(--shadow-md-sharp);\n --mds-push-notification-item-message-line-clamp: 3;\n --mds-push-notification-item-subject-line-clamp: 2;\n}\n```\n",
26265
+ "1. Description": "The `<mds-push-notification-item>` web component is a single notification card rendered inside its parent container [`<mds-push-notification>`](../mds-push-notification/AGENTS.md). It composes an avatar/image, a subject, a relative or formatted timestamp, a message body and an optional dismiss control into one toast-like row.\n\n#### Semantic Behavior\n\n- **Compound child only**: It must be placed as a direct default-slot child of `<mds-push-notification>`; it is not used standalone or mixed with other child types, since the parent animates intro/outro and manages stacking.\n- **Dismiss reports up, removal happens in the parent**: Clicking the built-in close button emits the bubbling `mdsPushNotificationItemClose` event, with the `id` of the item as `detail.id`; the parent runs the outro animation and removes the item. The item never removes itself.\n- **Parent-driven visibility lifecycle**: When the last item closes, the parent auto-hides the whole notification area.\n- **Timestamp rendering**: With `dateFormat=\"timeago\"` `datetime` shows a localized relative time (\"2 minutes ago\"); otherwise the value is treated as a date-format string for a static date.\n- **Localization**: The relative-time strings and the dismiss button title are localized (el/en/es/it).\n- **Conditional avatar vs. picture**: An `<mds-avatar>` is rendered when `icon` is set or `preview=\"avatar\"`; when `src` is set and `preview` is not `avatar`, an `<mds-img>` picture is rendered (next to the avatar when `icon` is also set).\n- **Slot detection**: The `badge` and `action` named slot wrappers stay hidden (`display: none`) until matching slotted children exist, so empty slots take no space.\n\n#### Properties & Visual Configurations\n\n- **`dismissible`**: Controls whether the dismiss button is shown. Add it to let the user close the notification manually; leave it off for items the user should not close.\n- **`deletable`** is the old name of `dismissible`, deprecated: the button dismisses the notification, it deletes nothing. It still works, and goes in the next major.\n- **`preview`**: Pick `avatar` to show the `src` image (or `initials`/`icon` fallback) as a compact round avatar, or `image` (default) to show `src` as a larger inline picture preview.\n- **`initials`**: Provided as the avatar fallback when no image is available; it overrides `tone`/`variant` styling so the user stays visually recognizable.\n- **`dateFormat`**: Use `timeago` for a live relative timestamp, or any date-format token string for a fixed display date.\n\nFor `tone` and `variant`, this component consumes the shared color ladders defined in [`agents/variants.md`](../../../../agents/variants.md); the values are forwarded to the underlying `<mds-avatar>` and follow the avatar tone/variant set rather than adding component-specific values.\n",
26266
+ "2. Pattern": "Correct and idiomatic ways to use the `<mds-push-notification-item>` component, ordered from most common to most specialized. Patterns 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 Message Notification\n\nThe minimal form: a message body with an icon and a relative timestamp. Always nest the item inside [`mds-push-notification`](../mds-push-notification/AGENTS.md), which manages stacking and animation.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/email\"\n subject=\"Nuovo messaggio\"\n message=\"Hai ricevuto 3 nuovi messaggi da account diversi\"\n datetime=\"2024-06-01T10:30:00\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Variant for Semantic Status\n\nUse `variant` to communicate meaning - success, warning, error, info - and `tone` to set visual weight. The values are forwarded to the internal `<mds-avatar>`.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/check-circle\"\n subject=\"Salvataggio completato\"\n message=\"Il documento e' stato salvato con successo\"\n datetime=\"2024-06-01T10:31:00\"\n variant=\"success\"\n tone=\"strong\"\n ></mds-push-notification-item>\n\n <mds-push-notification-item\n icon=\"mi/baseline/warning\"\n subject=\"Attenzione\"\n message=\"La sessione scadra' tra 5 minuti\"\n datetime=\"2024-06-01T10:32:00\"\n variant=\"warning\"\n tone=\"weak\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Dismissible Notification\n\nAdd the `dismissible` attribute to show the dismiss button, letting the user close the notification manually. Without it the notification cannot be dismissed by the user - keep it off for system notifications the user must not close.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n dismissible\n icon=\"mi/baseline/email\"\n subject=\"Nuovo messaggio\"\n message=\"Hai ricevuto un nuovo messaggio\"\n datetime=\"2024-06-01T09:00:00\"\n variant=\"info\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Action Buttons via the `action` Slot\n\nSlot one or more `<mds-button>` elements into `slot=\"action\"` for in-notification CTAs. Use `size=\"sm\"` to keep the actions compact.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/person\"\n subject=\"Mario Giannini\"\n message=\"Ciao, sono Mario, questo e' il mio contatto, buona giornata!\"\n datetime=\"2024-06-01T10:25:00\"\n variant=\"primary\"\n tone=\"strong\"\n >\n <mds-button slot=\"action\" variant=\"success\" tone=\"weak\" size=\"sm\" label=\"Accetta\"></mds-button>\n <mds-button slot=\"action\" variant=\"error\" tone=\"weak\" size=\"sm\" label=\"Ignora\"></mds-button>\n </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Badge Label via the `badge` Slot\n\nSlot an `<mds-badge>` into `slot=\"badge\"` to show a category or type label above the subject line.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/attach-file\"\n subject=\"Nuovo allegato\"\n message=\"Hai ricevuto un nuovo file allegato da Luca Bianchi\"\n datetime=\"2024-06-01T10:20:00\"\n variant=\"primary\"\n >\n <mds-badge slot=\"badge\" variant=\"amaranth\" tone=\"weak\" label=\"pdf\"></mds-badge>\n <mds-button slot=\"action\" tone=\"outline\" size=\"sm\" label=\"Scarica\"></mds-button>\n </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Avatar Mode with Image\n\nSet `src` and `preview=\"avatar\"` to display a user photo as a round avatar instead of the default full-width image preview.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n src=\"./avatar-sarah.jpeg\"\n preview=\"avatar\"\n subject=\"Sarah Ho\"\n message=\"Ciao, sono Sarah, questo e' il mio contatto, buona giornata!\"\n datetime=\"2024-06-01T10:15:00\"\n variant=\"primary\"\n tone=\"strong\"\n >\n <mds-button slot=\"action\" variant=\"success\" tone=\"weak\" size=\"sm\" label=\"Scrivi\"></mds-button>\n </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Avatar Mode with Initials Fallback\n\nWhen no image is available, set `initials` and `preview=\"avatar\"`. The initials override `tone` and `variant` coloring so the user stays visually distinguishable.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n initials=\"MG\"\n preview=\"avatar\"\n subject=\"Mario Giannini\"\n message=\"Ha modificato il documento condiviso\"\n datetime=\"2024-06-01T10:10:00\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Inline Image Preview\n\nOmit `preview=\"avatar\"` (or keep the default `image`) and supply `src` to show the image as a larger inline thumbnail - useful for file or media notifications.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n src=\"./book-cover-01.webp\"\n subject=\"Anteprima immagine\"\n message=\"La copertina e' stata aggiornata\"\n datetime=\"2024-06-01T10:05:00\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Fixed Date Format\n\nUse any `dayjs`-compatible format string as `date-format` to show a static date instead of the default relative \"time ago\" display.\n\n```html\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/event\"\n subject=\"Promemoria riunione\"\n message=\"La riunione di progetto e' fissata per domani\"\n datetime=\"2024-06-01T09:00:00\"\n date-format=\"DD/MM/YYYY\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Listening to the Dismiss Event\n\nListen to `mdsPushNotificationItemClose` to handle cleanup when the user dismisses the item. The parent `<mds-push-notification>` does this automatically, but you can also add your own logic (e.g. marking the notification read in the server). The event carries the `id` of the item in `detail.id`.\n\n```javascript\ndocument\n .querySelector('mds-push-notification-item')\n .addEventListener('mdsPushNotificationItemClose', (event) => {\n markNotificationRead(event.detail.id);\n });\n```\n\n#### Styling Customization\n\nCustomize the item only through its public `--mds-push-notification-item-*` CSS custom properties.\n\n```css\n.app-notifications mds-push-notification-item {\n --mds-push-notification-item-shadow: var(--shadow-md-sharp);\n --mds-push-notification-item-message-line-clamp: 3;\n --mds-push-notification-item-subject-line-clamp: 2;\n}\n```\n",
26105
26267
  "3. Antipattern": "Common incorrect uses of `<mds-push-notification-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/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Use the Item Outside Its Parent\n\n`<mds-push-notification-item>` is a compound child that must live inside [`<mds-push-notification>`](../mds-push-notification/AGENTS.md). The parent drives entry / exit animation, stacking, and auto-hide when the last item closes.\n\n```html\n<!-- INCORRECT -->\n<mds-push-notification-item\n icon=\"mi/baseline/email\"\n subject=\"Nuovo messaggio\"\n message=\"Hai ricevuto un nuovo messaggio\"\n></mds-push-notification-item>\n\n<!-- CORRECT -->\n<mds-push-notification>\n <mds-push-notification-item\n icon=\"mi/baseline/email\"\n subject=\"Nuovo messaggio\"\n message=\"Hai ricevuto un nuovo messaggio\"\n ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Do Not Put Content in the Default Slot\n\n`<mds-push-notification-item>` has no default slot. All text content goes through the `message` and `subject` props; interactive content goes into the named `action` or `badge` slots.\n\n```html\n<!-- INCORRECT -->\n<mds-push-notification-item>\n Hai un nuovo messaggio\n</mds-push-notification-item>\n\n<!-- CORRECT -->\n<mds-push-notification-item\n message=\"Hai un nuovo messaggio\"\n subject=\"Posta in arrivo\"\n></mds-push-notification-item>\n```\n\n#### Do Not Slot Arbitrary Content Into `action` Without `mds-button`\n\nThe `action` slot is designed for `<mds-button>` elements at `size=\"sm\"`. Slotting raw `<button>` or large components breaks layout alignment and loses Magma theming and keyboard semantics.\n\n```html\n<!-- INCORRECT -->\n<mds-push-notification-item subject=\"Richiesta\" message=\"Approva la richiesta di accesso\">\n <button slot=\"action\" class=\"btn\">Approva</button>\n</mds-push-notification-item>\n\n<!-- CORRECT -->\n<mds-push-notification-item subject=\"Richiesta\" message=\"Approva la richiesta di accesso\">\n <mds-button slot=\"action\" variant=\"success\" tone=\"weak\" size=\"sm\" label=\"Approva\"></mds-button>\n</mds-push-notification-item>\n```\n\n#### Do Not Mix `icon` and `src` With `preview=\"image\"`\n\nWhen `icon` is set, the component always renders an `<mds-avatar>` for the icon. If `src` is also set and `preview` is not `\"avatar\"`, an `<mds-img>` picture is rendered as well - producing two media areas side by side, which is almost never the intended layout. Pick one visual mode per notification.\n\n```html\n<!-- INCORRECT - both an icon avatar and an image preview render simultaneously -->\n<mds-push-notification-item\n icon=\"mi/baseline/photo\"\n src=\"./cover.jpg\"\n preview=\"image\"\n subject=\"Nuova foto\"\n message=\"La copertina e' stata aggiornata\"\n></mds-push-notification-item>\n\n<!-- CORRECT - icon only, no image -->\n<mds-push-notification-item\n icon=\"mi/baseline/photo\"\n subject=\"Nuova foto\"\n message=\"La copertina e' stata aggiornata\"\n></mds-push-notification-item>\n\n<!-- CORRECT - image preview only, no icon -->\n<mds-push-notification-item\n src=\"./cover.jpg\"\n subject=\"Nuova foto\"\n message=\"La copertina e' stata aggiornata\"\n></mds-push-notification-item>\n```\n\n#### Do Not Listen for the Native `close` DOM Event\n\nThe component emits `mdsPushNotificationItemClose`, not a native `close`. Listening for `close` never fires, and the `click` of the dismiss button does not leave the component (its handler calls `stopPropagation()`).\n\n```javascript\n// INCORRECT\nelement.addEventListener('close', handler);\n\n// CORRECT\nelement.addEventListener('mdsPushNotificationItemClose', handler);\n```\n\n#### Customize via Documented Vars, Not Internal Selectors\n\nThe supported customization surface is `--mds-push-notification-item-*` CSS custom properties and documented shadow parts (`actions`, `avatar`, `content`, `picture`). Targeting shadow-DOM internals via `::part()` on undocumented parts or via `>>>` will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-push-notification-item::part(header) {\n font-weight: bold;\n}\nmds-push-notification-item >>> .message {\n color: red;\n}\n\n/* CORRECT */\nmds-push-notification-item {\n --mds-push-notification-item-message-line-clamp: 3;\n --mds-push-notification-item-shadow: var(--shadow-md-sharp);\n}\nmds-push-notification-item::part(content) {\n gap: calc(var(--spacing) * 200);\n}\n```\n"
26106
26268
  },
26107
26269
  "props": [
@@ -26187,14 +26349,45 @@
26187
26349
  "mutable": true,
26188
26350
  "attr": "deletable",
26189
26351
  "reflectToAttr": true,
26190
- "docs": "Specifies if the component is dismissable; when set, a dismiss button is shown.",
26352
+ "docs": "Shows the dismiss button, as `dismissible` does.",
26191
26353
  "docsTags": [
26354
+ {
26355
+ "name": "deprecated",
26356
+ "text": "Use `dismissible`: the button dismisses the notification, it deletes nothing.\nGoes in the next major."
26357
+ },
26192
26358
  {
26193
26359
  "name": "default",
26194
26360
  "text": "false"
26195
26361
  }
26196
26362
  ],
26197
26363
  "default": "false",
26364
+ "deprecation": "Use `dismissible`: the button dismisses the notification, it deletes nothing.\nGoes in the next major.",
26365
+ "values": [
26366
+ {
26367
+ "type": "boolean"
26368
+ },
26369
+ {
26370
+ "type": "undefined"
26371
+ }
26372
+ ],
26373
+ "optional": true,
26374
+ "required": false,
26375
+ "getter": false,
26376
+ "setter": false
26377
+ },
26378
+ {
26379
+ "name": "dismissible",
26380
+ "type": "boolean | undefined",
26381
+ "complexType": {
26382
+ "original": "boolean",
26383
+ "resolved": "boolean | undefined",
26384
+ "references": {}
26385
+ },
26386
+ "mutable": true,
26387
+ "attr": "dismissible",
26388
+ "reflectToAttr": true,
26389
+ "docs": "Shows a dismiss button: activating it emits `mdsPushNotificationItemClose`, and a parent\n`mds-push-notification` takes the item out of the stack",
26390
+ "docsTags": [],
26198
26391
  "values": [
26199
26392
  {
26200
26393
  "type": "boolean"
@@ -26654,7 +26847,8 @@
26654
26847
  "mds-icon",
26655
26848
  "mds-text"
26656
26849
  ]
26657
- }
26850
+ },
26851
+ "storybook": "ui-push-notification-push-notification-item--docs"
26658
26852
  },
26659
26853
  {
26660
26854
  "filePath": "src/components/mds-quote/mds-quote.tsx",
@@ -26825,7 +27019,8 @@
26825
27019
  "mds-quote": [
26826
27020
  "mds-text"
26827
27021
  ]
26828
- }
27022
+ },
27023
+ "storybook": "ui-quote--docs"
26829
27024
  },
26830
27025
  {
26831
27026
  "filePath": "src/components/mds-radial-menu/mds-radial-menu.tsx",
@@ -27399,7 +27594,8 @@
27399
27594
  "mds-icon",
27400
27595
  "mds-text"
27401
27596
  ]
27402
- }
27597
+ },
27598
+ "storybook": "ui-radial-menu--docs"
27403
27599
  },
27404
27600
  {
27405
27601
  "filePath": "src/components/mds-radial-menu-item/mds-radial-menu-item.tsx",
@@ -27691,7 +27887,8 @@
27691
27887
  "mds-tooltip": [
27692
27888
  "mds-text"
27693
27889
  ]
27694
- }
27890
+ },
27891
+ "storybook": "ui-radial-menu-radial-menu-item--docs"
27695
27892
  },
27696
27893
  {
27697
27894
  "filePath": "src/components/mds-radial-progress/mds-radial-progress.tsx",
@@ -27949,7 +28146,8 @@
27949
28146
  "mds-progress": [
27950
28147
  "mds-radial-progress"
27951
28148
  ]
27952
- }
28149
+ },
28150
+ "storybook": "ui-radial-progress--docs"
27953
28151
  },
27954
28152
  {
27955
28153
  "filePath": "src/components/mds-separator/mds-separator.tsx",
@@ -27991,7 +28189,8 @@
27991
28189
  "mds-price-table-list": [
27992
28190
  "mds-separator"
27993
28191
  ]
27994
- }
28192
+ },
28193
+ "storybook": "ui-separator--docs"
27995
28194
  },
27996
28195
  {
27997
28196
  "filePath": "src/components/mds-spinner/mds-spinner.tsx",
@@ -28007,7 +28206,7 @@
28007
28206
  ],
28008
28207
  "usage": {
28009
28208
  "1. Description": "The `<mds-spinner>` web component is the Magma Design System's loading/await indicator: a self-contained, animated SVG spinner used standalone or embedded inside host components (`mds-button`, `mds-input`, `mds-entity`) to signal an in-progress, indeterminate operation. It has no HTML primitive equivalent and exposes no text content.\n\n#### Semantic Behavior\n\n- **Visibility is gated by `running`**: When `running` is absent/false the spinner is hidden and its animation is paused; setting `running` reveals it and starts the animation. The animation never runs while hidden, for performance.\n- **No interactivity or accessibility role**: It is decorative - not focusable, emits no events, has no ARIA role, and is not form-associated. Any loading semantics (e.g. `aria-busy`) must be set by the surrounding context.\n- **Reduced-motion and contrast aware**: The animation slows down (8s per turn, it never stops) when the Magma animation preference reduces motion (`pref-animation-reduce`, `mds-pref-animation`, or the OS `prefers-reduced-motion` under `system`), and the color is strengthened under the contrast preference, without consumer intervention.\n\n#### Properties & Visual Configurations\n\nThe component exposes a single behavioral prop:\n\n- **`running`** is the master switch that both shows the spinner and runs its animation; treat it as a boolean presence attribute and drive it from the consuming component's loading/await state rather than toggling visibility manually.\n\n#### Other behavioral props\n\n- **`--mds-spinner-duration`** (CSS custom property, default `0.725s`) tunes the rotation speed of the spin animation; override it on the host to slow down or speed up the indicator without touching markup.\n",
28010
- "2. Pattern": "Correct and idiomatic ways to use the `<mds-spinner>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Spinner - Hidden by Default\n\nThe component is invisible and animation-paused until `running` is set. Render it into the DOM early and toggle `running` when a request starts; removing the attribute (or setting the prop to `undefined`) hides it again when done.\n\n```html\n<!-- Spinner hidden - no running attribute -->\n<mds-spinner></mds-spinner>\n\n<!-- Spinner visible and animating -->\n<mds-spinner running></mds-spinner>\n```\n\n#### Inline Loading Indicator\n\nPlace the spinner next to a label to signal that a section is loading. The spinner is painted in the accent color (`--magma-accent-fg`) by default; set `color` on the host to match the surrounding text instead.\n\n```html\n<div class=\"loading-row\">\n <mds-spinner running></mds-spinner>\n <span>Caricamento dati in corso...</span>\n</div>\n```\n\n#### Full-Page or Overlay Loading State\n\nCentre the spinner over a region with a wrapper. Drive `running` programmatically - set it when the async operation starts, remove it when done.\n\n```html\n<div class=\"overlay\">\n <mds-spinner running></mds-spinner>\n</div>\n```\n\n```css\n.overlay {\n align-items: center;\n display: flex;\n inset: 0;\n justify-content: center;\n position: absolute;\n}\n```\n\n#### Inside `mds-button` (via `await`)\n\n`mds-button` manages its own internal `<mds-spinner>` automatically through its `await` prop. Do not add a separate `<mds-spinner>` next to a button - use `await` on the button itself.\n\n```html\n<!-- While an async operation is in flight -->\n<mds-button label=\"Salvataggio in corso...\" await variant=\"primary\" tone=\"strong\"></mds-button>\n```\n\n#### Controlling Animation Speed\n\nUse the `--mds-spinner-duration` CSS custom property to tune the rotation speed. Set it on the host element - shorter values spin faster, longer values spin slower. Reduced motion still slows the spinner down to 8s per turn, whatever this property says.\n\n```css\n.fast-indicator mds-spinner {\n --mds-spinner-duration: 0.4s;\n}\n\n.slow-indicator mds-spinner {\n --mds-spinner-duration: 1.5s;\n}\n```\n\n#### Accessible Loading Region\n\n`<mds-spinner>` is purely decorative and carries no ARIA role. Announce the loading state to screen readers by adding `aria-busy` and `aria-live` on the surrounding container, not on the spinner itself.\n\n```html\n<section aria-busy=\"true\" aria-live=\"polite\" aria-label=\"Ricerca in corso\">\n <mds-spinner running></mds-spinner>\n</section>\n```\n\n#### Colour Customization via CSS Color\n\nThe spinner stroke inherits `color` from the host, so you can recolour it without touching shadow internals. Use a semantic colour role so dark mode and high-contrast modes keep working.\n\n```css\n.status-warning-spinner mds-spinner {\n color: rgb(var(--magma-warning-text-default));\n}\n```\n\n```html\n<div class=\"status-warning-spinner\">\n <mds-spinner running></mds-spinner>\n</div>\n```\n",
28209
+ "2. Pattern": "Correct and idiomatic ways to use the `<mds-spinner>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Spinner\n\nA spinner shows and animates while `running` is set.\n\n```html\n<mds-spinner running></mds-spinner>\n```\n\nWithout `running` the component is invisible and its animation paused. Render it into the DOM early and set `running` when a request starts; removing the attribute (or setting the prop to `undefined`) hides it again when done.\n\n```html\n<!-- Rendered early, hidden until a request starts -->\n<mds-spinner></mds-spinner>\n```\n\n#### Inline Loading Indicator\n\nPlace the spinner next to a label to signal that a section is loading. The spinner is painted in the accent color (`--magma-accent-fg`) by default; set `color` on the host to match the surrounding text instead.\n\n```html\n<div class=\"loading-row\">\n <mds-spinner running></mds-spinner>\n <span>Caricamento dati in corso...</span>\n</div>\n```\n\n#### Full-Page or Overlay Loading State\n\nCentre the spinner over a region with a wrapper. Drive `running` programmatically - set it when the async operation starts, remove it when done.\n\n```html\n<div class=\"overlay\">\n <mds-spinner running></mds-spinner>\n</div>\n```\n\n```css\n.overlay {\n align-items: center;\n display: flex;\n inset: 0;\n justify-content: center;\n position: absolute;\n}\n```\n\n#### Inside `mds-button` (via `await`)\n\n`mds-button` manages its own internal `<mds-spinner>` automatically through its `await` prop. Do not add a separate `<mds-spinner>` next to a button - use `await` on the button itself.\n\n```html\n<!-- While an async operation is in flight -->\n<mds-button label=\"Salvataggio in corso...\" await variant=\"primary\" tone=\"strong\"></mds-button>\n```\n\n#### Controlling Animation Speed\n\nUse the `--mds-spinner-duration` CSS custom property to tune the rotation speed. Set it on the host element - shorter values spin faster, longer values spin slower. Reduced motion still slows the spinner down to 8s per turn, whatever this property says.\n\n```css\n.fast-indicator mds-spinner {\n --mds-spinner-duration: 0.4s;\n}\n\n.slow-indicator mds-spinner {\n --mds-spinner-duration: 1.5s;\n}\n```\n\n#### Accessible Loading Region\n\n`<mds-spinner>` is purely decorative and carries no ARIA role. Announce the loading state to screen readers by adding `aria-busy` and `aria-live` on the surrounding container, not on the spinner itself.\n\n```html\n<section aria-busy=\"true\" aria-live=\"polite\" aria-label=\"Ricerca in corso\">\n <mds-spinner running></mds-spinner>\n</section>\n```\n\n#### Colour Customization via CSS Color\n\nThe spinner stroke inherits `color` from the host, so you can recolour it without touching shadow internals. Use a semantic colour role so dark mode and high-contrast modes keep working.\n\n```css\n.status-warning-spinner mds-spinner {\n color: rgb(var(--magma-warning-text-default));\n}\n```\n\n```html\n<div class=\"status-warning-spinner\">\n <mds-spinner running></mds-spinner>\n</div>\n```\n",
28011
28210
  "3. Antipattern": "Common incorrect uses of `<mds-spinner>`. 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/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Set `running=\"false\"` to Hide the Spinner\n\nThe component's styles key on the presence of `running` (`:host([running])`). Stencil reads `\"false\"` as `false` and, since `running` is 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 - or set the prop to `undefined` - to stop and hide the spinner.\n\n```html\n<!-- INCORRECT -->\n<mds-spinner running=\"false\"></mds-spinner>\n\n<!-- CORRECT -->\n<mds-spinner></mds-spinner>\n```\n\n#### Do Not Show Spinner Without `running` and Expect It to Animate\n\nThe spinner renders as invisible (`opacity: 0`, `transform: scale(0)`) and with the animation paused when `running` is absent. Toggling CSS visibility or opacity from outside will not start the animation - you must set the `running` attribute.\n\n```html\n<!-- INCORRECT -->\n<mds-spinner style=\"opacity: 1; transform: none;\"></mds-spinner>\n\n<!-- CORRECT -->\n<mds-spinner running></mds-spinner>\n```\n\n#### Do Not Add ARIA Roles or Labels to the Spinner Itself\n\nThe spinner is decorative - it has no semantic content and must not become a labelled landmark or a status region. Screen readers should be informed of loading state through a parent container with `aria-busy` / `aria-live`, not through attributes placed on `<mds-spinner>`.\n\n```html\n<!-- INCORRECT -->\n<mds-spinner running role=\"status\" aria-label=\"Caricamento\"></mds-spinner>\n\n<!-- CORRECT -->\n<div role=\"status\" aria-live=\"polite\" aria-label=\"Caricamento\">\n <mds-spinner running></mds-spinner>\n</div>\n```\n\n#### Do Not Add a Separate Spinner Alongside `mds-button`\n\n`mds-button` controls its own internal `<mds-spinner>` through the `await` prop. An extra spinner next to the button leaves the button clickable while the operation runs; `await` shows the button's own spinner and blocks interaction.\n\n```html\n<!-- INCORRECT -->\n<mds-button label=\"Salva\" variant=\"primary\"></mds-button>\n<mds-spinner running></mds-spinner>\n\n<!-- CORRECT -->\n<mds-button label=\"Salva\" await variant=\"primary\"></mds-button>\n```\n\n#### Do Not Pierce Shadow DOM to Change the SVG Colour\n\nThe only documented customization surface is the `color` CSS property on the host (inherited by the internal stroke) and the `--mds-spinner-duration` CSS custom property. Targeting internals via `>>>` or undocumented selectors couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-spinner >>> .await-icon svg {\n stroke: red;\n}\n\n/* CORRECT */\nmds-spinner {\n color: rgb(var(--magma-danger-text-default));\n}\n```\n\n#### Do Not Override `--mds-spinner-duration` to Pause or Stop the Animation\n\nSetting an extremely long or `infinite` duration is not a supported way to pause the spinner. Use the `running` attribute to start and stop the animation - the component manages animation-play-state itself.\n\n```css\n/* INCORRECT */\nmds-spinner {\n --mds-spinner-duration: 9999s;\n}\n```\n\n```html\n<!-- CORRECT - remove the attribute to stop -->\n<mds-spinner></mds-spinner>\n```\n"
28012
28211
  },
28013
28212
  "props": [
@@ -28074,7 +28273,8 @@
28074
28273
  "mds-input": [
28075
28274
  "mds-spinner"
28076
28275
  ]
28077
- }
28276
+ },
28277
+ "storybook": "ui-spinner--docs"
28078
28278
  },
28079
28279
  {
28080
28280
  "filePath": "src/components/mds-status-bar/mds-status-bar.tsx",
@@ -28334,7 +28534,8 @@
28334
28534
  "mds-icon",
28335
28535
  "mds-text"
28336
28536
  ]
28337
- }
28537
+ },
28538
+ "storybook": "ui-status-bar--docs"
28338
28539
  },
28339
28540
  {
28340
28541
  "filePath": "src/components/mds-stepper-bar/mds-stepper-bar.tsx",
@@ -28539,7 +28740,8 @@
28539
28740
  "states": [],
28540
28741
  "dependents": [],
28541
28742
  "dependencies": [],
28542
- "dependencyGraph": {}
28743
+ "dependencyGraph": {},
28744
+ "storybook": "ui-stepper-bar--docs"
28543
28745
  },
28544
28746
  {
28545
28747
  "filePath": "src/components/mds-stepper-bar-item/mds-stepper-bar-item.tsx",
@@ -28999,7 +29201,8 @@
28999
29201
  "mds-icon",
29000
29202
  "mds-text"
29001
29203
  ]
29002
- }
29204
+ },
29205
+ "storybook": "ui-stepper-bar-stepper-bar-item--docs"
29003
29206
  },
29004
29207
  {
29005
29208
  "filePath": "src/components/mds-tab/mds-tab.tsx",
@@ -29519,7 +29722,8 @@
29519
29722
  "mds-pref-theme": [
29520
29723
  "mds-tab"
29521
29724
  ]
29522
- }
29725
+ },
29726
+ "storybook": "ui-tab--docs"
29523
29727
  },
29524
29728
  {
29525
29729
  "filePath": "src/components/mds-tab-bar/mds-tab-bar.tsx",
@@ -29585,7 +29789,8 @@
29585
29789
  "states": [],
29586
29790
  "dependents": [],
29587
29791
  "dependencies": [],
29588
- "dependencyGraph": {}
29792
+ "dependencyGraph": {},
29793
+ "storybook": "ui-tab-bar--docs"
29589
29794
  },
29590
29795
  {
29591
29796
  "filePath": "src/components/mds-tab-bar-item/mds-tab-bar-item.tsx",
@@ -29794,7 +29999,8 @@
29794
29999
  "mds-icon",
29795
30000
  "mds-text"
29796
30001
  ]
29797
- }
30002
+ },
30003
+ "storybook": "ui-tab-bar-tab-bar-item--docs"
29798
30004
  },
29799
30005
  {
29800
30006
  "filePath": "src/components/mds-tab-item/mds-tab-item.tsx",
@@ -30376,7 +30582,8 @@
30376
30582
  "mds-pref-theme": [
30377
30583
  "mds-tab-item"
30378
30584
  ]
30379
- }
30585
+ },
30586
+ "storybook": "ui-tab-tab-item--docs"
30380
30587
  },
30381
30588
  {
30382
30589
  "filePath": "src/components/mds-table/mds-table.tsx",
@@ -30759,7 +30966,8 @@
30759
30966
  "mds-badge": [
30760
30967
  "mds-text"
30761
30968
  ]
30762
- }
30969
+ },
30970
+ "storybook": "layout-table--docs"
30763
30971
  },
30764
30972
  {
30765
30973
  "filePath": "src/components/mds-table-body/mds-table-body.tsx",
@@ -30881,7 +31089,8 @@
30881
31089
  "states": [],
30882
31090
  "dependents": [],
30883
31091
  "dependencies": [],
30884
- "dependencyGraph": {}
31092
+ "dependencyGraph": {},
31093
+ "storybook": "layout-table-body--docs"
30885
31094
  },
30886
31095
  {
30887
31096
  "filePath": "src/components/mds-table-cell/mds-table-cell.tsx",
@@ -30988,7 +31197,8 @@
30988
31197
  "mds-table-row": [
30989
31198
  "mds-table-cell"
30990
31199
  ]
30991
- }
31200
+ },
31201
+ "storybook": "layout-table-cell--docs"
30992
31202
  },
30993
31203
  {
30994
31204
  "filePath": "src/components/mds-table-footer/mds-table-footer.tsx",
@@ -31059,7 +31269,8 @@
31059
31269
  "mds-table-footer": [
31060
31270
  "mds-table-cell"
31061
31271
  ]
31062
- }
31272
+ },
31273
+ "storybook": "layout-table-footer--docs"
31063
31274
  },
31064
31275
  {
31065
31276
  "filePath": "src/components/mds-table-header/mds-table-header.tsx",
@@ -31253,7 +31464,8 @@
31253
31464
  "mds-icon",
31254
31465
  "mds-text"
31255
31466
  ]
31256
- }
31467
+ },
31468
+ "storybook": "layout-table-header--docs"
31257
31469
  },
31258
31470
  {
31259
31471
  "filePath": "src/components/mds-table-header-cell/mds-table-header-cell.tsx",
@@ -31468,7 +31680,8 @@
31468
31680
  "mds-table-header": [
31469
31681
  "mds-table-header-cell"
31470
31682
  ]
31471
- }
31683
+ },
31684
+ "storybook": "layout-table-header-cell--docs"
31472
31685
  },
31473
31686
  {
31474
31687
  "filePath": "src/components/mds-table-row/mds-table-row.tsx",
@@ -31492,7 +31705,7 @@
31492
31705
  ],
31493
31706
  "usage": {
31494
31707
  "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",
31495
- "2. Pattern": "Correct and idiomatic ways to use the `<mds-table-row>` component, ordered from most common to most specialized. Patterns 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\n`mds-table-row` has no public CSS custom property: a 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",
31708
+ "2. Pattern": "Correct and idiomatic ways to use the `<mds-table-row>` component, ordered from most common to most specialized. Patterns 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",
31496
31709
  "3. Antipattern": "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/anti-patterns.md`](../../../../agents/anti-patterns.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"
31497
31710
  },
31498
31711
  "props": [
@@ -31663,6 +31876,12 @@
31663
31876
  "events": [],
31664
31877
  "listeners": [],
31665
31878
  "styles": [
31879
+ {
31880
+ "name": "--mds-table-row-actions-background",
31881
+ "annotation": "prop",
31882
+ "docs": "Read-only: the background the actions box paints in the current state of the row (at rest, on hover, while a column sorts a selectable table), for content of the `action` slot that paints it too when it moves out of the box. The box sets it itself, so a value set from outside changes nothing.",
31883
+ "visibility": "public"
31884
+ },
31666
31885
  {
31667
31886
  "name": "--mds-table-row-actions-gap",
31668
31887
  "annotation": "prop",
@@ -31720,7 +31939,8 @@
31720
31939
  "mds-icon",
31721
31940
  "mds-text"
31722
31941
  ]
31723
- }
31942
+ },
31943
+ "storybook": "layout-table-row--docs"
31724
31944
  },
31725
31945
  {
31726
31946
  "filePath": "src/components/mds-text/mds-text.tsx",
@@ -32466,7 +32686,8 @@
32466
32686
  "mds-usage": [
32467
32687
  "mds-text"
32468
32688
  ]
32469
- }
32689
+ },
32690
+ "storybook": "design-typography--docs"
32470
32691
  },
32471
32692
  {
32472
32693
  "filePath": "src/components/mds-toast/mds-toast.tsx",
@@ -32493,9 +32714,9 @@
32493
32714
  }
32494
32715
  ],
32495
32716
  "usage": {
32496
- "1. Description": "The `<mds-toast>` web component is the transient notification surface of the Magma Design System, used to surface brief, non-blocking feedback messages that appear over the viewport and auto-dismiss after a timeout. It has no native HTML equivalent and orchestrates its own visibility, positioning, and auto-close lifecycle.\n\n#### Semantic Behavior\n\n- **Announced**: The host is a status region (`role=\"status\"`): the message is read out when the toast shows it, without moving the focus. While not visible, the message is hidden from assistive technologies too, not only moved out of the viewport. Inside an `<mds-toast-region>` the region is the status region and the toast has no role of its own.\n- **Inside a region**: In an `<mds-toast-region>` the toast is laid out by the region, in a column with the other toasts visible at the same time, instead of being fixed at its edge on its own; the region gives it its `position`. A hidden toast in a region takes no room once its exit is over, and its entrance and exit are a short fade towards the edge.\n- **Auto-dismiss timer**: When `visible` is true and `duration` is a positive number, an internal timer counts down and then sets `visible` back to `false`; setting `duration` to `0` (or falsy) keeps the toast on screen until it is closed intentionally.\n- **The timer waits for the person**: The countdown stops while the pointer is over the toast or the focus is inside it (on its action, on its hide button), and goes on with the time that was left once both have left: the toast does not take its action away while the person is reading it or reaching the action.\n- **Hide button**: With `deletable`, the toast shows at its end a button with an arrow towards the edge it leaves by (down at the bottom, up at the top), named in the current language and reachable with the keyboard; it hides the toast. It is an arrow and not a cross because the action next to it may itself be a cancel (\"Annulla\"): the arrow only sends the message away.\n- **Close event**: Whenever the toast hides, the component emits `mdsToastClose` once, after the outro animation - consumers should listen for this to remove the toast from the DOM or update queue state. The `reason` of its detail says who hid it: `timeout` (the `duration` ran out), `close` (the person, with the hide button) or `hide` (your code removed `visible`). A toast shown again before the outro is over emits nothing for that hiding.\n- **Reactive timer**: Showing the toast again (`visible` back to true) or changing `duration` at runtime restarts the countdown; hiding it stops the countdown, so a toast hidden by your code closes once, as `hide`, and never again as `timeout`.\n- **Conditional regions**: The text region renders only when the host has inner content, and the action region is shown only while a `[slot=\"action\"]` child is present, following the children added or removed later - empty slots produce no layout.\n- **Default-slot is text**: The default slot is intended for a plain text string only; icons go in the `icon` slot and interactive controls in the `action` slot.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` / `tone` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md); `<mds-toast>` consumes the theme variant set and the minimal tone set (`'strong'` / `'weak'`) without adding component-specific values.\n\n#### Other behavioral props\n\n- **`position`** anchors the toast to one of the six viewport corners/edges (top or bottom, left/center/right), driving both placement and the direction of the entry/exit animation; pick the edge that matches where users expect ephemeral feedback to surface.\n- **`visible`** is the controlled on/off switch for the toast; toggling it drives the show/hide animation and the auto-dismiss timer rather than mounting or unmounting the element.\n- **`duration`** is the visibility window in milliseconds before auto-dismiss; use a longer value for messages that carry an action the user must reach, and `0` for toasts that must stay until explicitly closed.\n- **`deletable`** shows the hide button; give it to a toast that stays (`duration=\"0\"`) when its action is not what every person wants (\"Riprova\"), so the person can send the message away without using it.\n\n#### Slots\n\n- **`icon`** holds a leading glyph (recommended `mds-icon`); **`action`** holds interactive follow-ups (recommended `mds-button`) and, when present, renders inside a dedicated actions container.\n",
32497
- "2. Pattern": "Correct and idiomatic ways to use the `<mds-toast>` component, ordered from most common to most specialized. Patterns 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 Toast\n\nThe simplest form. Set `visible` to show the toast; the default slot holds the message text only. The component auto-dismisses after the default 5000 ms.\n\n```html\n<mds-toast visible>\n Operazione completata con successo\n</mds-toast>\n```\n\n#### Status Variants\n\nUse `variant` to communicate the meaning of the feedback. The status family (`error`, `warning`, `info`, `success`) maps directly to the nature of the event. Do not pick a variant for its color alone.\n\n```html\n<!-- Conferma positiva -->\n<mds-toast visible variant=\"success\">\n Documento salvato correttamente\n</mds-toast>\n\n<!-- Errore bloccante -->\n<mds-toast visible variant=\"error\">\n Errore durante il salvataggio. Riprova.\n</mds-toast>\n\n<!-- Avviso non bloccante -->\n<mds-toast visible variant=\"warning\">\n La sessione scade tra 5 minuti\n</mds-toast>\n\n<!-- Informazione neutrale -->\n<mds-toast visible variant=\"info\">\n Aggiornamento disponibile\n</mds-toast>\n```\n\n#### Tone for Emphasis\n\nPair `variant` with `tone` to adjust visual weight. `strong` (default) uses the stronger tint of the variant and a larger shadow; `weak` uses a softer tint and a smaller shadow for lower emphasis.\n\n```html\n<!-- Forte enfasi: errore urgente -->\n<mds-toast visible variant=\"error\" tone=\"strong\">\n Connessione persa\n</mds-toast>\n\n<!-- Enfasi ridotta: info secondaria -->\n<mds-toast visible variant=\"info\" tone=\"weak\">\n Sincronizzazione in background\n</mds-toast>\n```\n\n#### Toast with Icon\n\nUse the `icon` slot with an `<mds-icon>` to add a leading glyph. The icon color is tuned per variant.\n\n```html\n<mds-toast visible variant=\"success\">\n <mds-icon slot=\"icon\" name=\"mi/baseline/check-circle\"></mds-icon>\n File caricato con successo\n</mds-toast>\n```\n\n#### Toast with Action\n\nUse the `action` slot with an `<mds-button>` to offer a follow-up. The action region appears only while a `[slot=\"action\"]` child is present, also when it is added after the first render - no empty layout is produced otherwise.\n\n```html\n<mds-toast visible variant=\"error\">\n <mds-icon slot=\"icon\" name=\"mi/baseline/error-outline\"></mds-icon>\n Invio non riuscito\n <mds-button slot=\"action\" size=\"sm\" variant=\"error\" tone=\"weak\">\n Riprova\n </mds-button>\n</mds-toast>\n```\n\n#### Persistent Toast (No Auto-Dismiss)\n\nSet `duration=\"0\"` to keep the toast visible until the user explicitly acts. Use this when the message carries an action the user must not miss. Hide it from your action handler by removing `visible`, and add `deletable` so the person can send the message away without using the action.\n\n```html\n<mds-toast visible variant=\"warning\" duration=\"0\" deletable>\n <mds-icon slot=\"icon\" name=\"mi/baseline/warning\"></mds-icon>\n Sessione in scadenza\n <mds-button slot=\"action\" size=\"sm\" variant=\"warning\" tone=\"weak\">\n Rinnova\n </mds-button>\n</mds-toast>\n```\n\n#### Custom Auto-Dismiss Duration\n\nOverride the 5000 ms default when the message needs more reading time (e.g. it carries an action) or can disappear faster (e.g. a trivial confirmation). Duration is in milliseconds.\n\n```html\n<!-- Messaggio breve: 2 secondi -->\n<mds-toast visible variant=\"success\" duration=\"2000\">\n Copiato negli appunti\n</mds-toast>\n\n<!-- Con azione: 8 secondi -->\n<mds-toast visible variant=\"info\" duration=\"8000\">\n Importazione completata con 3 avvisi\n <mds-button slot=\"action\" size=\"sm\" variant=\"info\" tone=\"weak\">\n Vedi report\n </mds-button>\n</mds-toast>\n```\n\n#### Several Toasts at Once\n\nTwo toasts visible at the same time with the same `position` are drawn at the same place, one over the other. Append the toasts of the application to one `<mds-toast-region>`, placed once in its shell: it lines them up at its edge, announces them, and makes room when too many show at once.\n\n```html\n<mds-toast-region position=\"bottom-center\">\n <mds-toast visible variant=\"success\">Documento salvato</mds-toast>\n <mds-toast visible variant=\"success\">Link copiato negli appunti</mds-toast>\n</mds-toast-region>\n```\n\n#### Positioning\n\nUse `position` to anchor the toast to one of the six viewport edges. Pick the edge that matches the application's layout convention - bottom-center is the default and works for most surfaces.\n\n```html\n<!-- Predefinito: centro in basso -->\n<mds-toast visible variant=\"info\" position=\"bottom-center\">\n Messaggio salvato\n</mds-toast>\n\n<!-- Angolo in alto a destra (toolbar / panel) -->\n<mds-toast visible variant=\"success\" position=\"top-right\">\n Impostazioni aggiornate\n</mds-toast>\n```\n\n#### Listening for the Close Event\n\nListen for `mdsToastClose` to remove the toast from the DOM or update queue state after the outro animation completes. It is emitted once for every hiding, whoever hid the toast, and `event.detail.reason` says who: `timeout`, `close` (the hide button) or `hide` (your code). Do not react to `visible` becoming `false` directly - the animation is still running at that point.\n\n```javascript\ndocument.querySelector('mds-toast').addEventListener('mdsToastClose', (event) => {\n // rimuovi il toast dalla coda o aggiorna lo stato dell'applicazione\n toastQueue.shift();\n if (event.detail.reason === 'close') {\n // la persona ha mandato via il messaggio senza usare l'azione\n }\n});\n```\n\n#### Styling Customization\n\nStyle the toast only through its public `--mds-toast-*` CSS custom properties: the background, the text colour, the width and the shadow. Set them on the host element 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.app-notifications mds-toast {\n --mds-toast-background: rgb(var(--magma-surface-inverse));\n --mds-toast-color: rgb(var(--magma-on-inverse));\n --mds-toast-width: 480px;\n --mds-toast-shadow: var(--shadow-xl);\n}\n```\n",
32498
- "3. Antipattern": "Common incorrect uses of `<mds-toast>`. 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/anti-patterns.md`](../../../../agents/anti-patterns.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 rendered inside the caption text and break the layout. Use the `icon` slot for an icon and the `action` slot for buttons.\n\n```html\n<!-- INCORRECT -->\n<mds-toast visible variant=\"error\">\n <strong>Errore:</strong> salvataggio fallito\n <mds-button>Riprova</mds-button>\n</mds-toast>\n\n<!-- CORRECT -->\n<mds-toast visible variant=\"error\">\n <mds-icon slot=\"icon\" name=\"mi/baseline/error-outline\"></mds-icon>\n Salvataggio fallito\n <mds-button slot=\"action\" size=\"sm\" variant=\"error\" tone=\"weak\">Riprova</mds-button>\n</mds-toast>\n```\n\n#### Do Not Leave a Persistent Toast Without a Way to Send It Away\n\nA toast with `duration=\"0\"` stays until something hides it. When its action is not what the person wants, nothing makes it go away: it covers the page until your code removes it. Add `deletable`.\n\n```html\n<!-- INCORRECT - only \"Riprova\" makes it go away -->\n<mds-toast visible variant=\"error\" duration=\"0\">\n Invio non riuscito\n <mds-button slot=\"action\" size=\"sm\" variant=\"error\" tone=\"weak\">Riprova</mds-button>\n</mds-toast>\n\n<!-- CORRECT - the arrow sends the message away -->\n<mds-toast visible variant=\"error\" duration=\"0\" deletable>\n Invio non riuscito\n <mds-button slot=\"action\" size=\"sm\" variant=\"error\" tone=\"weak\">Riprova</mds-button>\n</mds-toast>\n```\n\n#### Do Not Set `duration=\"0\"` to Mean \"Use the Default\"\n\nSetting `duration=\"0\"` explicitly disables auto-dismiss and keeps the toast on screen until the user closes it. To use the 5000 ms default, omit the attribute entirely.\n\n```html\n<!-- INCORRECT - disables auto-dismiss unintentionally -->\n<mds-toast visible variant=\"success\" duration=\"0\">\n Documento salvato\n</mds-toast>\n\n<!-- CORRECT - default 5000 ms applies -->\n<mds-toast visible variant=\"success\">\n Documento salvato\n</mds-toast>\n```\n\n#### Do Not Use `visible=\"false\"` to Hide the Toast\n\nSetting a boolean attribute to the string `\"false\"` leaves the attribute on the element. The toast itself reads it as hidden, but every presence check (`[visible]`, `hasAttribute('visible')`, as in the cleanup code below) still reads it as visible. Remove the attribute entirely (or set the prop to `undefined`) to hide the toast.\n\n```html\n<!-- INCORRECT - presence checks still read the toast as visible -->\n<mds-toast visible=\"false\" variant=\"info\">\n Sincronizzazione in corso\n</mds-toast>\n\n<!-- CORRECT - attribute absent means hidden -->\n<mds-toast variant=\"info\">\n Sincronizzazione in corso\n</mds-toast>\n```\n\n#### Do Not React to `visible` Becoming `false` to Clean Up\n\nWhen the timer fires it sets `visible` to `false`, but the outro animation is still running. Listening to that attribute change too early removes the element mid-animation. Wait for `mdsToastClose`, which fires after the animation completes.\n\n```javascript\n// INCORRECT - element may still be animating\nconst toast = document.querySelector('mds-toast');\nconst observer = new MutationObserver(() => {\n if (!toast.hasAttribute('visible')) {\n toast.remove();\n }\n});\nobserver.observe(toast, { attributes: true });\n\n// CORRECT - fires after the outro animation\ntoast.addEventListener('mdsToastClose', () => {\n toast.remove();\n});\n```\n\n#### Do Not Use a Variant Without Checking Its Acceptance\n\n`<mds-toast>` accepts `variant` values from `ThemeVariantType` but ships CSS overrides only for `light`, `dark`, `error`, `warning`, `info`, and `success`. Using `variant=\"primary\"` or `variant=\"ai\"` is valid by type but produces no themed color overrides - the toast falls back to its base inverse colors, the same as `dark`. Stick to the six variants above.\n\n```html\n<!-- INCORRECT - no color override; looks identical to variant=\"dark\" -->\n<mds-toast visible variant=\"primary\">\n Azione confermata\n</mds-toast>\n\n<!-- CORRECT - uses a variant with full CSS support -->\n<mds-toast visible variant=\"success\">\n Azione confermata\n</mds-toast>\n```\n\n#### Do Not Use `tone=\"outline\"` or `tone=\"text\"`\n\n`<mds-toast>` uses `ToneMinimalVariantType`, which accepts only `strong` and `weak`. Passing `tone=\"outline\"` or `tone=\"text\"` silently falls back to the default and produces no visual difference.\n\n```html\n<!-- INCORRECT - value not in ToneMinimalVariantType -->\n<mds-toast visible variant=\"info\" tone=\"outline\">\n Aggiornamento disponibile\n</mds-toast>\n\n<!-- CORRECT -->\n<mds-toast visible variant=\"info\" tone=\"weak\">\n Aggiornamento disponibile\n</mds-toast>\n```\n\n#### Do Not Customize via Undocumented Shadow Parts or Internal Selectors\n\nThe supported surface is the public `--mds-toast-*` CSS custom properties. There are no documented `::part()` targets for `<mds-toast>`; targeting internal class names with `::part()`, `>>>`, or attribute-selector hacks couples your code to the shadow DOM implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-toast >>> .dialog {\n border-radius: 0;\n}\n\n/* CORRECT - use the public custom properties */\nmds-toast {\n --mds-toast-background: rgb(var(--magma-surface-inverse));\n --mds-toast-color: rgb(var(--magma-on-inverse));\n --mds-toast-width: 360px;\n}\n```\n"
32717
+ "1. Description": "The `<mds-toast>` web component is the transient notification surface of the Magma Design System, used to surface brief, non-blocking feedback messages that appear over the viewport and auto-dismiss after a timeout. It has no native HTML equivalent and orchestrates its own visibility, positioning, and auto-close lifecycle.\n\n#### Semantic Behavior\n\n- **Announced**: The host is a status region (`role=\"status\"`): the message is read out when the toast shows it, without moving the focus. While not visible, the message is hidden from assistive technologies too, not only moved out of the viewport. Inside an `<mds-toast-region>` the region is the status region and the toast has no role of its own.\n- **Inside a region**: In an `<mds-toast-region>` the toast is laid out by the region, in a column with the other toasts visible at the same time, instead of being fixed at its edge on its own; the region gives it its `position`. A hidden toast in a region takes no room once its exit is over, and its entrance and exit are a short fade towards the edge.\n- **Auto-dismiss timer**: When `visible` is true and `duration` is a positive number, an internal timer counts down and then sets `visible` back to `false`; setting `duration` to `0` (or falsy) keeps the toast on screen until it is closed intentionally.\n- **The timer waits for the person**: The countdown stops while the pointer is over the toast or the focus is inside it (on its action, on its hide button), and goes on with the time that was left once both have left: the toast does not take its action away while the person is reading it or reaching the action.\n- **Hide button**: With `dismissible`, the toast shows at its end a button with an arrow towards the edge it leaves by (down at the bottom, up at the top), named in the current language and reachable with the keyboard; it hides the toast. It is an arrow and not a cross because the action next to it may itself be a cancel (\"Annulla\"): the arrow only sends the message away.\n- **Close event**: Whenever the toast hides, the component emits `mdsToastClose` once, after the outro animation - consumers should listen for this to remove the toast from the DOM or update queue state. The `reason` of its detail says who hid it: `timeout` (the `duration` ran out), `close` (the person, with the hide button) or `hide` (your code removed `visible`). A toast shown again before the outro is over emits nothing for that hiding.\n- **Reactive timer**: Showing the toast again (`visible` back to true) or changing `duration` at runtime restarts the countdown; hiding it stops the countdown, so a toast hidden by your code closes once, as `hide`, and never again as `timeout`.\n- **Conditional regions**: The text region renders only when the host has inner content, and the action region is shown only while a `[slot=\"action\"]` child is present, following the children added or removed later - empty slots produce no layout.\n- **Default-slot is text**: The default slot is intended for a plain text string only; icons go in the `icon` slot and interactive controls in the `action` slot.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` / `tone` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md); `<mds-toast>` consumes the theme variant set and the minimal tone set (`'strong'` / `'weak'`) without adding component-specific values.\n\n#### Other behavioral props\n\n- **`position`** anchors the toast to one of the six viewport corners/edges (top or bottom, left/center/right), driving both placement and the direction of the entry/exit animation; pick the edge that matches where users expect ephemeral feedback to surface.\n- **`visible`** is the controlled on/off switch for the toast; toggling it drives the show/hide animation and the auto-dismiss timer rather than mounting or unmounting the element.\n- **`duration`** is the visibility window in milliseconds before auto-dismiss; use a longer value for messages that carry an action the user must reach, and `0` for toasts that must stay until explicitly closed.\n- **`dismissible`** shows the hide button; give it to a toast that stays (`duration=\"0\"`) when its action is not what every person wants (\"Riprova\"), so the person can send the message away without using it.\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\n#### Slots\n\n- **`icon`** holds a leading glyph (recommended `mds-icon`); **`action`** holds interactive follow-ups (recommended `mds-button`) and, when present, renders inside a dedicated actions container.\n",
32718
+ "2. Pattern": "Correct and idiomatic ways to use the `<mds-toast>` component, ordered from most common to most specialized. Patterns 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 Toast\n\nThe simplest form. Set `visible` to show the toast; the default slot holds the message text only. The component auto-dismisses after the default 5000 ms.\n\n```html\n<mds-toast visible>\n Operazione completata con successo\n</mds-toast>\n```\n\n#### Status Variants\n\nUse `variant` to communicate the meaning of the feedback. The status family (`error`, `warning`, `info`, `success`) maps directly to the nature of the event. Do not pick a variant for its color alone.\n\n```html\n<!-- Conferma positiva -->\n<mds-toast visible variant=\"success\">\n Documento salvato correttamente\n</mds-toast>\n\n<!-- Errore bloccante -->\n<mds-toast visible variant=\"error\">\n Errore durante il salvataggio. Riprova.\n</mds-toast>\n\n<!-- Avviso non bloccante -->\n<mds-toast visible variant=\"warning\">\n La sessione scade tra 5 minuti\n</mds-toast>\n\n<!-- Informazione neutrale -->\n<mds-toast visible variant=\"info\">\n Aggiornamento disponibile\n</mds-toast>\n```\n\n#### Tone for Emphasis\n\nPair `variant` with `tone` to adjust visual weight. `strong` (default) uses the stronger tint of the variant and a larger shadow; `weak` uses a softer tint and a smaller shadow for lower emphasis.\n\n```html\n<!-- Forte enfasi: errore urgente -->\n<mds-toast visible variant=\"error\" tone=\"strong\">\n Connessione persa\n</mds-toast>\n\n<!-- Enfasi ridotta: info secondaria -->\n<mds-toast visible variant=\"info\" tone=\"weak\">\n Sincronizzazione in background\n</mds-toast>\n```\n\n#### Toast with Icon\n\nUse the `icon` slot with an `<mds-icon>` to add a leading glyph. The icon color is tuned per variant.\n\n```html\n<mds-toast visible variant=\"success\">\n <mds-icon slot=\"icon\" name=\"mi/baseline/check-circle\"></mds-icon>\n File caricato con successo\n</mds-toast>\n```\n\n#### Toast with Action\n\nUse the `action` slot with an `<mds-button>` to offer a follow-up. The action region appears only while a `[slot=\"action\"]` child is present, also when it is added after the first render - no empty layout is produced otherwise.\n\n```html\n<mds-toast visible variant=\"error\">\n <mds-icon slot=\"icon\" name=\"mi/baseline/error-outline\"></mds-icon>\n Invio non riuscito\n <mds-button slot=\"action\" size=\"sm\" variant=\"error\" tone=\"weak\">\n Riprova\n </mds-button>\n</mds-toast>\n```\n\n#### Persistent Toast (No Auto-Dismiss)\n\nSet `duration=\"0\"` to keep the toast visible until the user explicitly acts. Use this when the message carries an action the user must not miss. Hide it from your action handler by removing `visible`, and add `dismissible` so the person can send the message away without using the action.\n\n```html\n<mds-toast visible variant=\"warning\" duration=\"0\" dismissible>\n <mds-icon slot=\"icon\" name=\"mi/baseline/warning\"></mds-icon>\n Sessione in scadenza\n <mds-button slot=\"action\" size=\"sm\" variant=\"warning\" tone=\"weak\">\n Rinnova\n </mds-button>\n</mds-toast>\n```\n\n#### Custom Auto-Dismiss Duration\n\nOverride the 5000 ms default when the message needs more reading time (e.g. it carries an action) or can disappear faster (e.g. a trivial confirmation). Duration is in milliseconds.\n\n```html\n<!-- Messaggio breve: 2 secondi -->\n<mds-toast visible variant=\"success\" duration=\"2000\">\n Copiato negli appunti\n</mds-toast>\n\n<!-- Con azione: 8 secondi -->\n<mds-toast visible variant=\"info\" duration=\"8000\">\n Importazione completata con 3 avvisi\n <mds-button slot=\"action\" size=\"sm\" variant=\"info\" tone=\"weak\">\n Vedi report\n </mds-button>\n</mds-toast>\n```\n\n#### Several Toasts at Once\n\nTwo toasts visible at the same time with the same `position` are drawn at the same place, one over the other. Append the toasts of the application to one `<mds-toast-region>`, placed once in its shell: it lines them up at its edge, announces them, and makes room when too many show at once.\n\n```html\n<mds-toast-region position=\"bottom-center\">\n <mds-toast visible variant=\"success\">Documento salvato</mds-toast>\n <mds-toast visible variant=\"success\">Link copiato negli appunti</mds-toast>\n</mds-toast-region>\n```\n\n#### Positioning\n\nUse `position` to anchor the toast to one of the six viewport edges. Pick the edge that matches the application's layout convention - bottom-center is the default and works for most surfaces.\n\n```html\n<!-- Predefinito: centro in basso -->\n<mds-toast visible variant=\"info\" position=\"bottom-center\">\n Messaggio salvato\n</mds-toast>\n\n<!-- Angolo in alto a destra (toolbar / panel) -->\n<mds-toast visible variant=\"success\" position=\"top-right\">\n Impostazioni aggiornate\n</mds-toast>\n```\n\n#### Listening for the Close Event\n\nListen for `mdsToastClose` to remove the toast from the DOM or update queue state after the outro animation completes. It is emitted once for every hiding, whoever hid the toast, and `event.detail.reason` says who: `timeout`, `close` (the hide button) or `hide` (your code). Do not react to `visible` becoming `false` directly - the animation is still running at that point.\n\n```javascript\ndocument.querySelector('mds-toast').addEventListener('mdsToastClose', (event) => {\n // rimuovi il toast dalla coda o aggiorna lo stato dell'applicazione\n toastQueue.shift();\n if (event.detail.reason === 'close') {\n // la persona ha mandato via il messaggio senza usare l'azione\n }\n});\n```\n\n#### Styling Customization\n\nStyle the toast only through its public `--mds-toast-*` CSS custom properties: the background, the text colour, the width and the shadow. Set them on the host element 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.app-notifications mds-toast {\n --mds-toast-background: rgb(var(--magma-surface-inverse));\n --mds-toast-color: rgb(var(--magma-on-inverse));\n --mds-toast-width: 480px;\n --mds-toast-shadow: var(--shadow-xl);\n}\n```\n",
32719
+ "3. Antipattern": "Common incorrect uses of `<mds-toast>`. 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/anti-patterns.md`](../../../../agents/anti-patterns.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 rendered inside the caption text and break the layout. Use the `icon` slot for an icon and the `action` slot for buttons.\n\n```html\n<!-- INCORRECT -->\n<mds-toast visible variant=\"error\">\n <strong>Errore:</strong> salvataggio fallito\n <mds-button>Riprova</mds-button>\n</mds-toast>\n\n<!-- CORRECT -->\n<mds-toast visible variant=\"error\">\n <mds-icon slot=\"icon\" name=\"mi/baseline/error-outline\"></mds-icon>\n Salvataggio fallito\n <mds-button slot=\"action\" size=\"sm\" variant=\"error\" tone=\"weak\">Riprova</mds-button>\n</mds-toast>\n```\n\n#### Do Not Leave a Persistent Toast Without a Way to Send It Away\n\nA toast with `duration=\"0\"` stays until something hides it. When its action is not what the person wants, nothing makes it go away: it covers the page until your code removes it. Add `dismissible`.\n\n```html\n<!-- INCORRECT - only \"Riprova\" makes it go away -->\n<mds-toast visible variant=\"error\" duration=\"0\">\n Invio non riuscito\n <mds-button slot=\"action\" size=\"sm\" variant=\"error\" tone=\"weak\">Riprova</mds-button>\n</mds-toast>\n\n<!-- CORRECT - the arrow sends the message away -->\n<mds-toast visible variant=\"error\" duration=\"0\" dismissible>\n Invio non riuscito\n <mds-button slot=\"action\" size=\"sm\" variant=\"error\" tone=\"weak\">Riprova</mds-button>\n</mds-toast>\n```\n\n#### Do Not Set `duration=\"0\"` to Mean \"Use the Default\"\n\nSetting `duration=\"0\"` explicitly disables auto-dismiss and keeps the toast on screen until the user closes it. To use the 5000 ms default, omit the attribute entirely.\n\n```html\n<!-- INCORRECT - disables auto-dismiss unintentionally -->\n<mds-toast visible variant=\"success\" duration=\"0\">\n Documento salvato\n</mds-toast>\n\n<!-- CORRECT - default 5000 ms applies -->\n<mds-toast visible variant=\"success\">\n Documento salvato\n</mds-toast>\n```\n\n#### Do Not Use `visible=\"false\"` to Hide the Toast\n\nSetting a boolean attribute to the string `\"false\"` leaves the attribute on the element. The toast itself reads it as hidden, but every presence check (`[visible]`, `hasAttribute('visible')`, as in the cleanup code below) still reads it as visible. Remove the attribute entirely (or set the prop to `undefined`) to hide the toast.\n\n```html\n<!-- INCORRECT - presence checks still read the toast as visible -->\n<mds-toast visible=\"false\" variant=\"info\">\n Sincronizzazione in corso\n</mds-toast>\n\n<!-- CORRECT - attribute absent means hidden -->\n<mds-toast variant=\"info\">\n Sincronizzazione in corso\n</mds-toast>\n```\n\n#### Do Not React to `visible` Becoming `false` to Clean Up\n\nWhen the timer fires it sets `visible` to `false`, but the outro animation is still running. Listening to that attribute change too early removes the element mid-animation. Wait for `mdsToastClose`, which fires after the animation completes.\n\n```javascript\n// INCORRECT - element may still be animating\nconst toast = document.querySelector('mds-toast');\nconst observer = new MutationObserver(() => {\n if (!toast.hasAttribute('visible')) {\n toast.remove();\n }\n});\nobserver.observe(toast, { attributes: true });\n\n// CORRECT - fires after the outro animation\ntoast.addEventListener('mdsToastClose', () => {\n toast.remove();\n});\n```\n\n#### Do Not Use a Variant Without Checking Its Acceptance\n\n`<mds-toast>` accepts `variant` values from `ThemeVariantType` but ships CSS overrides only for `light`, `dark`, `error`, `warning`, `info`, and `success`. Using `variant=\"primary\"` or `variant=\"ai\"` is valid by type but produces no themed color overrides - the toast falls back to its base inverse colors, the same as `dark`. Stick to the six variants above.\n\n```html\n<!-- INCORRECT - no color override; looks identical to variant=\"dark\" -->\n<mds-toast visible variant=\"primary\">\n Azione confermata\n</mds-toast>\n\n<!-- CORRECT - uses a variant with full CSS support -->\n<mds-toast visible variant=\"success\">\n Azione confermata\n</mds-toast>\n```\n\n#### Do Not Use `tone=\"outline\"` or `tone=\"text\"`\n\n`<mds-toast>` uses `ToneMinimalVariantType`, which accepts only `strong` and `weak`. Passing `tone=\"outline\"` or `tone=\"text\"` silently falls back to the default and produces no visual difference.\n\n```html\n<!-- INCORRECT - value not in ToneMinimalVariantType -->\n<mds-toast visible variant=\"info\" tone=\"outline\">\n Aggiornamento disponibile\n</mds-toast>\n\n<!-- CORRECT -->\n<mds-toast visible variant=\"info\" tone=\"weak\">\n Aggiornamento disponibile\n</mds-toast>\n```\n\n#### Do Not Customize via Undocumented Shadow Parts or Internal Selectors\n\nThe supported surface is the public `--mds-toast-*` CSS custom properties. There are no documented `::part()` targets for `<mds-toast>`; targeting internal class names with `::part()`, `>>>`, or attribute-selector hacks couples your code to the shadow DOM implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-toast >>> .dialog {\n border-radius: 0;\n}\n\n/* CORRECT - use the public custom properties */\nmds-toast {\n --mds-toast-background: rgb(var(--magma-surface-inverse));\n --mds-toast-color: rgb(var(--magma-on-inverse));\n --mds-toast-width: 360px;\n}\n```\n"
32499
32720
  },
32500
32721
  "props": [
32501
32722
  {
@@ -32509,6 +32730,38 @@
32509
32730
  "mutable": false,
32510
32731
  "attr": "deletable",
32511
32732
  "reflectToAttr": false,
32733
+ "docs": "Shows the hide button, as `dismissible` does.",
32734
+ "docsTags": [
32735
+ {
32736
+ "name": "deprecated",
32737
+ "text": "Use `dismissible`: the button dismisses the message, it deletes nothing.\nGoes in the next major."
32738
+ }
32739
+ ],
32740
+ "deprecation": "Use `dismissible`: the button dismisses the message, it deletes nothing.\nGoes in the next major.",
32741
+ "values": [
32742
+ {
32743
+ "type": "boolean"
32744
+ },
32745
+ {
32746
+ "type": "undefined"
32747
+ }
32748
+ ],
32749
+ "optional": true,
32750
+ "required": false,
32751
+ "getter": false,
32752
+ "setter": false
32753
+ },
32754
+ {
32755
+ "name": "dismissible",
32756
+ "type": "boolean | undefined",
32757
+ "complexType": {
32758
+ "original": "boolean",
32759
+ "resolved": "boolean | undefined",
32760
+ "references": {}
32761
+ },
32762
+ "mutable": false,
32763
+ "attr": "dismissible",
32764
+ "reflectToAttr": false,
32512
32765
  "docs": "Shows a button that hides the toast, an arrow towards the edge the toast leaves by",
32513
32766
  "docsTags": [],
32514
32767
  "values": [
@@ -32535,7 +32788,7 @@
32535
32788
  "mutable": true,
32536
32789
  "attr": "duration",
32537
32790
  "reflectToAttr": true,
32538
- "docs": "If set, specifies the visibility duration in milliseconds of the element inside the viewport, when the time is up the visible property will be set to false. The countdown waits while the pointer is over the toast or the focus is inside it. If the duration is set to 0 the toast stays until it is hidden: give it `deletable` so the person can hide it too.",
32791
+ "docs": "If set, specifies the visibility duration in milliseconds of the element inside the viewport, when the time is up the visible property will be set to false. The countdown waits while the pointer is over the toast or the focus is inside it. If the duration is set to 0 the toast stays until it is hidden: give it `dismissible` so the person can hide it too.",
32539
32792
  "docsTags": [
32540
32793
  {
32541
32794
  "name": "default",
@@ -32846,7 +33099,8 @@
32846
33099
  "mds-icon",
32847
33100
  "mds-text"
32848
33101
  ]
32849
- }
33102
+ },
33103
+ "storybook": "ui-toast--docs"
32850
33104
  },
32851
33105
  {
32852
33106
  "filePath": "src/components/mds-toast-region/mds-toast-region.tsx",
@@ -32866,7 +33120,7 @@
32866
33120
  ],
32867
33121
  "usage": {
32868
33122
  "1. Description": "The `<mds-toast-region>` web component is the place where an application shows its toasts: placed once in the application shell, at an edge of the viewport, it lines up the `<mds-toast>` elements visible at the same time, each one readable, and announces them to assistive technologies. It has no native HTML equivalent.\n\n#### Semantic Behavior\n\n- **One place for the toasts**: The region is fixed at the edge named by `position`; the toasts inside it are laid out in its flow, in a column with a gap, instead of each one being fixed on its own. The newest toast (the last one in the page) sits at the edge, where the toasts come in.\n- **The others close the gap**: A hidden toast in the region takes no room once its exit is over, so the toasts left move up to the edge; the exit itself is a short fade towards the edge, not a slide over the other toasts.\n- **Position of the toasts**: The region gives its `position` to every toast inside it, the ones added later too, and again when its own `position` changes.\n- **Live region**: The host is a status region (`role=\"status\"`, `aria-live=\"polite\"`, not atomic) that is in the page before any message, so a toast added or shown inside it is read out without moving the focus, and only that toast. The toasts inside it drop their own status role.\n- **The most toasts at once**: When a toast shows while `max` toasts are already visible, the region hides the oldest ones with a `duration`, in the order they were shown, and each one emits `mdsToastClose` with `reason: 'hide'`. A toast that stays (`duration=\"0\"`) and the toast just shown are never hidden, so the region may hold more than `max` until one of them goes.\n- **Below the dialogs**: The region is a fixed layer of the page, not a top layer element: an `<mds-modal>` opened later covers it and makes it inert, toasts and announcements included. A message about an open dialog belongs inside the dialog.\n- **Toasts outside the region**: A toast that is not inside a region keeps placing itself at its own `position`, as before.\n\n#### Properties & Visual Configurations\n\n- **`position`** picks the edge and the alignment of the column: top or bottom, left, center or right. Pick the edge where the application expects transient feedback; one region per application is the rule.\n- **`max`** is how many toasts may be visible at once before the oldest one with a timer leaves to make room; keep it small, a column of toasts covers the page.\n",
32869
- "2. Pattern": "Correct and idiomatic ways to use the `<mds-toast-region>` component, ordered from most common to most specialized. The toasts follow the patterns of `<mds-toast>`; the shared component rules live in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### One Region in the Application Shell\n\nPlace one region in the shell of the application, outside the content that changes from page to page, so it is in the page before any message. Every toast of the application goes into it.\n\n```html\n<body>\n <main>\n <!-- contenuto dell'applicazione -->\n </main>\n <mds-toast-region></mds-toast-region>\n</body>\n```\n\n#### Showing a Toast From Code\n\nCreate the toast, append it to the region and show it; remove it from the page once it has closed. The region places it, announces it, and makes room for it.\n\n```javascript\nconst region = document.querySelector('mds-toast-region');\n\nconst showToast = (text, variant = 'success') => {\n const toast = document.createElement('mds-toast');\n toast.variant = variant;\n toast.textContent = text;\n toast.addEventListener('mdsToastClose', () => toast.remove());\n region.append(toast);\n toast.visible = true;\n};\n\nshowToast('Documento salvato');\n```\n\n#### A Message That Stays Among Confirmations\n\nAn error that the person must act on stays (`duration=\"0\"`) with its action and the hide button, while the confirmations around it come and go: the region never hides a toast that stays to make room.\n\n```html\n<mds-toast-region>\n <mds-toast visible variant=\"error\" duration=\"0\" deletable>\n Invio non riuscito\n <mds-button slot=\"action\" size=\"sm\" variant=\"error\" tone=\"weak\">Riprova</mds-button>\n </mds-toast>\n <mds-toast visible variant=\"success\">Bozza salvata</mds-toast>\n</mds-toast-region>\n```\n\n#### At the Top Edge\n\nSet `position` on the region, not on the toasts: it lines the toasts up at that edge, the newest one at the top, and gives them the position, so they come in and leave from that edge.\n\n```html\n<mds-toast-region position=\"top-right\"></mds-toast-region>\n```\n\n#### Fewer Toasts at Once\n\nLower `max` for an application with frequent confirmations or little room: when one more toast shows, the oldest one with a timer leaves first.\n\n```html\n<mds-toast-region max=\"2\"></mds-toast-region>\n```\n\n#### Spacing Between the Toasts\n\nChange the space between the toasts with `--mds-toast-region-gap`.\n\n```css\nmds-toast-region {\n --mds-toast-region-gap: 12px;\n}\n```\n",
33123
+ "2. Pattern": "Correct and idiomatic ways to use the `<mds-toast-region>` component, ordered from most common to most specialized. The toasts follow the patterns of `<mds-toast>`; the shared component rules live in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### One Region in the Application Shell\n\nThe region holds the `<mds-toast>` elements of the application: every toast of the application goes into it, and the region lines them up at its edge and announces them. A toast shown in it leaves after its `duration`.\n\n```html\n<mds-toast-region>\n <mds-toast visible variant=\"success\">Documento salvato</mds-toast>\n</mds-toast-region>\n```\n\nPlace one region in the shell of the application, outside the content that changes from page to page, so it is in the page before any message; the toasts are added to it from code (see the next pattern).\n\n```html\n<body>\n <main>\n <!-- contenuto dell'applicazione -->\n </main>\n <mds-toast-region></mds-toast-region>\n</body>\n```\n\n#### Showing a Toast From Code\n\nCreate the toast, append it to the region and show it; remove it from the page once it has closed. The region places it, announces it, and makes room for it.\n\n```javascript\nconst region = document.querySelector('mds-toast-region');\n\nconst showToast = (text, variant = 'success') => {\n const toast = document.createElement('mds-toast');\n toast.variant = variant;\n toast.textContent = text;\n toast.addEventListener('mdsToastClose', () => toast.remove());\n region.append(toast);\n toast.visible = true;\n};\n\nshowToast('Documento salvato');\n```\n\n#### A Message That Stays Among Confirmations\n\nAn error that the person must act on stays (`duration=\"0\"`) with its action and the hide button, while the confirmations around it come and go: the region never hides a toast that stays to make room.\n\n```html\n<mds-toast-region>\n <mds-toast visible variant=\"error\" duration=\"0\" dismissible>\n Invio non riuscito\n <mds-button slot=\"action\" size=\"sm\" variant=\"error\" tone=\"weak\">Riprova</mds-button>\n </mds-toast>\n <mds-toast visible variant=\"success\">Bozza salvata</mds-toast>\n</mds-toast-region>\n```\n\n#### At the Top Edge\n\nSet `position` on the region, not on the toasts: it lines the toasts up at that edge, the newest one at the top, and gives them the position, so they come in and leave from that edge.\n\n```html\n<mds-toast-region position=\"top-right\"></mds-toast-region>\n```\n\n#### Fewer Toasts at Once\n\nLower `max` for an application with frequent confirmations or little room: when one more toast shows, the oldest one with a timer leaves first.\n\n```html\n<mds-toast-region max=\"2\"></mds-toast-region>\n```\n\n#### Spacing Between the Toasts\n\nChange the space between the toasts with `--mds-toast-region-gap`.\n\n```css\nmds-toast-region {\n --mds-toast-region-gap: 12px;\n}\n```\n",
32870
33124
  "3. Antipattern": "Common incorrect uses of `<mds-toast-region>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Place a Region in Every Page or Component\n\nTwo regions at the same edge draw their toasts at the same place, one over the other, which is the problem the region solves. A region created together with its message is also not in the page before it, so the message may not be announced.\n\n```html\n<!-- INCORRECT - one region per form, created with the message -->\n<form>\n <mds-toast-region>\n <mds-toast visible>Modulo inviato</mds-toast>\n </mds-toast-region>\n</form>\n\n<!-- CORRECT - one region in the shell, the toasts appended to it -->\n<mds-toast-region></mds-toast-region>\n```\n\n#### Do Not Set `position` on the Toasts Inside a Region\n\nThe region gives its `position` to every toast inside it, so the one set on a toast is replaced. Set it on the region.\n\n```html\n<!-- INCORRECT - replaced by the region -->\n<mds-toast-region>\n <mds-toast visible position=\"top-right\">Impostazioni aggiornate</mds-toast>\n</mds-toast-region>\n\n<!-- CORRECT -->\n<mds-toast-region position=\"top-right\">\n <mds-toast visible>Impostazioni aggiornate</mds-toast>\n</mds-toast-region>\n```\n\n#### Do Not Send a Message About an Open Dialog to the Region\n\nWhile an `mds-modal` is open, everything outside it is inert, the region included: its toast cannot be used and is not announced. Show the message inside the dialog.\n\n```html\n<!-- INCORRECT - the error of the dialog goes behind it -->\n<mds-modal opened>\n <form>...</form>\n</mds-modal>\n<mds-toast-region>\n <mds-toast visible variant=\"error\" duration=\"0\">Salvataggio non riuscito</mds-toast>\n</mds-toast-region>\n\n<!-- CORRECT - the error is in the dialog -->\n<mds-modal opened>\n <mds-banner variant=\"error\">Salvataggio non riuscito</mds-banner>\n <form></form>\n</mds-modal>\n```\n"
32871
33125
  },
32872
33126
  "props": [
@@ -32978,7 +33232,8 @@
32978
33232
  "states": [],
32979
33233
  "dependents": [],
32980
33234
  "dependencies": [],
32981
- "dependencyGraph": {}
33235
+ "dependencyGraph": {},
33236
+ "storybook": "ui-toast-toast-region--docs"
32982
33237
  },
32983
33238
  {
32984
33239
  "filePath": "src/components/mds-tooltip/mds-tooltip.tsx",
@@ -33516,7 +33771,8 @@
33516
33771
  "mds-radial-menu-item": [
33517
33772
  "mds-tooltip"
33518
33773
  ]
33519
- }
33774
+ },
33775
+ "storybook": "ui-tooltip--docs"
33520
33776
  },
33521
33777
  {
33522
33778
  "filePath": "src/components/mds-tree/mds-tree.tsx",
@@ -33536,7 +33792,7 @@
33536
33792
  ],
33537
33793
  "usage": {
33538
33794
  "1. Description": "The `<mds-tree>` web component is the root container of the Magma Design System tree view, organizing a hierarchy of slotted `<mds-tree-item>` nodes into an expandable/collapsible structure. It owns no visual row of its own: it is a compound parent that configures, stacks, and propagates state to its children.\n\n#### Semantic Behavior\n\n- **Compound parent**: The default slot accepts only `<mds-tree-item>` elements; the tree itself renders nothing but the slot and acts as the configuration and coordination root for the hierarchy.\n- **Accessibility**: The tree is a list of its items (`role=\"list\"`, named by `label`), and the items of a branch are a list inside their item, so a screen reader announces the level and the size of every branch. It is not a `role=\"tree\"`, which promises arrow-key navigation and leaves no room for the actions of an item: every button stays a Tab stop. The items of a closed branch are out of the tab order.\n- **Depth seeding**: Its direct children are assigned `depth = 0`, which removes the branch connector lines from the first level; deeper levels are indented by their nesting.\n- **Cascading `expanded`**: `expanded` on the tree, set in the markup or changed at runtime, propagates to every descendant item, opening or collapsing the whole hierarchy at once - except children marked `async`, which are left for on-demand resolution. Items added later, a branch loaded on demand, take the tree's `expanded`, `toggle`, `togglePosition`, `appearance` and `truncate` when they arrive; the items already there keep the state the user gave them.\n- **Cascading `toggle` and `truncate`**: Changing the toggle icon or the truncation mode on the tree pushes the value down to all descendant items so the whole tree stays visually consistent.\n- **Async branches**: When `async` is set on an item, its branch is expected to resolve its children after the click rather than expanding from pre-rendered content; such items are excluded from the bulk `expanded` cascade.\n\n#### Properties & Visual Configurations\n\n- **`appearance`** controls whether the depth-indicating branch decorations (connector lines and dots) are drawn: `'depth'` shows the guide lines that visualize nesting; `'none'` removes them for a flat look.\n- **`actions`** governs how per-item action controls are surfaced: `'auto'` reveals them on hover, `'visible'` keeps them always shown.\n- **`toggle`** selects the expand/collapse glyph for every item - `'chevron'` for a generic disclosure arrow, `'folder'` for a file-explorer metaphor; **`togglePosition`** places that glyph at the `'left'` or `'right'` of the label.\n\n#### Other behavioral props\n\n- **`truncate`** sets how item labels overflow: `'word'` truncates the line, `'all'` clamps to multiple lines (paired with the `--mds-tree-line-clamp` custom property), `'none'` lets text wrap freely.\n- **`expanded`** is the only mutable, reflected state prop; set it on the root to open the entire tree on first render, or change it to open or close the entire tree programmatically.\n",
33539
- "2. Pattern": "Correct and idiomatic ways to use the `<mds-tree>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Minimal Flat List\n\nThe simplest usage: a list of root-level nodes with no nesting. Every `<mds-tree-item>` must be a direct child of `<mds-tree>`.\n\n```html\n<mds-tree>\n <mds-tree-item label=\"Bacheca\"></mds-tree-item>\n <mds-tree-item label=\"Documenti\"></mds-tree-item>\n <mds-tree-item label=\"Impostazioni\"></mds-tree-item>\n</mds-tree>\n```\n\n#### Nested Hierarchy\n\nPlace `<mds-tree-item>` elements inside other `<mds-tree-item>` elements to build depth. The tree seeds `depth = 0` on direct children, which drops their branch connector lines; nested items are indented by their nesting.\n\n```html\n<mds-tree>\n <mds-tree-item label=\"Direzione generale\">\n <mds-tree-item label=\"Segreteria\">\n <mds-tree-item label=\"Protocollo\"></mds-tree-item>\n <mds-tree-item label=\"Archivio\"></mds-tree-item>\n </mds-tree-item>\n <mds-tree-item label=\"Risorse umane\"></mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n```\n\n#### Programmatic Expand / Collapse\n\nChange `expanded` on `<mds-tree>` at runtime to open or close the entire hierarchy at once. This cascades to all descendant items except those marked `async`, also when `expanded` is set in the markup; to start with a single branch open set `expanded` on that item instead.\n\n```html\n<!-- A branch expanded on mount -->\n<mds-tree id=\"albero-pratiche\">\n <mds-tree-item label=\"Pratiche in corso\" expanded>\n <mds-tree-item label=\"Pratica 001/2025\"></mds-tree-item>\n <mds-tree-item label=\"Pratica 002/2025\"></mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n\n<script>\n // Open or close the whole hierarchy later\n document.getElementById('albero-pratiche').expanded = true;\n</script>\n```\n\n#### Folder Toggle Style\n\nUse `toggle=\"folder\"` for file-explorer metaphors. The toggle icon switches between a closed and open folder glyph when the item is expanded or collapsed.\n\n```html\n<mds-tree toggle=\"folder\" actions=\"visible\">\n <mds-tree-item label=\"Fascicoli\">\n <mds-tree-item label=\"2025\">\n <mds-tree-item label=\"Fascicolo 001\"></mds-tree-item>\n <mds-tree-item label=\"Fascicolo 002\"></mds-tree-item>\n </mds-tree-item>\n <mds-tree-item label=\"2024\">\n <mds-tree-item label=\"Fascicolo 099\"></mds-tree-item>\n </mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n```\n\n#### Right-Positioned Toggle for Navigation Menus\n\nSet `toggle-position=\"right\"` and `appearance=\"none\"` for a flat navigation-menu look where the expand chevron sits at the trailing edge of the row.\n\n```html\n<mds-tree toggle=\"chevron\" toggle-position=\"right\" appearance=\"none\">\n <mds-tree-item label=\"Protocollazione documenti\">\n <mds-tree-item label=\"Nuovo protocollo in arrivo\"></mds-tree-item>\n <mds-tree-item label=\"Nuovo protocollo in partenza\"></mds-tree-item>\n </mds-tree-item>\n <mds-tree-item label=\"Gestione allegati\">\n <mds-tree-item label=\"Scansione multipla\"></mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n```\n\n#### Per-Item Actions via the `action` Slot\n\nSlot `<mds-button>` or `<mds-icon>` elements into each `<mds-tree-item>` with `slot=\"action\"`. Use `actions=\"auto\"` (default) to reveal them on hover, or `actions=\"visible\"` to always show them.\n\n```html\n<mds-tree actions=\"auto\">\n <mds-tree-item label=\"Relazione annuale 2025\">\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/download\"\n variant=\"dark\"\n tone=\"text\"\n title=\"Scarica\"\n ></mds-button>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/more-vert\"\n variant=\"dark\"\n tone=\"text\"\n title=\"Altre opzioni\"\n ></mds-button>\n <mds-tree-item label=\"Capitolo 1\"></mds-tree-item>\n <mds-tree-item label=\"Capitolo 2\"></mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n```\n\n#### Listening to Expand and Collapse Events\n\n`<mds-tree-item>` emits `mdsTreeItemCollapse` when it closes, and `mdsTreeItemExpand` only when an item marked `async` is asked to open (see below): opening a regular item emits nothing. Both events bubble, so one listener on the tree catches them. Listen via `addEventListener` - do not rely on native `change` / `click` bubbling through shadow DOM.\n\n```html\n<mds-tree id=\"albero-categorie\">\n <mds-tree-item label=\"Categoria A\">\n <mds-tree-item label=\"Sottocategoria A1\"></mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n\n<script>\n // emitted only by items marked async\n document.getElementById('albero-categorie').addEventListener('mdsTreeItemExpand', (event) => {\n console.log('espanso:', event.detail.element.label);\n });\n\n document.getElementById('albero-categorie').addEventListener('mdsTreeItemCollapse', (event) => {\n console.log('collassato:', event.detail.element.label);\n });\n</script>\n```\n\n#### Async Lazy-Loading Branches\n\nMark a `<mds-tree-item>` with `async` when its children must be fetched on demand. The item shows a loading spinner on click and emits `mdsTreeItemExpand`. Resolve the branch by calling `element.expand()` on the item once data is ready, then remove `async` so that reopening the branch later does not fetch it again. An item looks for child items only when it first renders: one that has none then shows no toggle (and no spinner), and children appended later do not add it.\n\n```html\n<mds-tree>\n <mds-tree-item label=\"Comune di Rimini\" icon=\"mgg/historic-building\">\n <mds-tree-item label=\"Ufficio\" async class=\"ufficio-item\" icon=\"mi/baseline/desk\">\n <!-- children appended by the script below -->\n </mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n\n<script>\n document.querySelector('.ufficio-item').addEventListener('mdsTreeItemExpand', async (event) => {\n const { element } = event.detail;\n if (!element.async) return;\n const children = await fetchChildren(element.label);\n children.forEach((nome) => {\n const item = document.createElement('mds-tree-item');\n item.label = nome;\n element.appendChild(item);\n });\n element.expand();\n element.async = false;\n });\n</script>\n```\n\n#### Icon on Individual Items\n\nUse the `icon` prop on `<mds-tree-item>` to show a glyph next to the label. Reference icons by their slug from the Magma icon library.\n\n```html\n<mds-tree toggle=\"chevron\">\n <mds-tree-item label=\"Comune di Rimini\" icon=\"mgg/historic-building\">\n <mds-tree-item label=\"Sindaco\" icon=\"mdi/handshake\">\n <mds-tree-item label=\"Segretario generale\" icon=\"mi/baseline/draw\"></mds-tree-item>\n </mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n```\n\n#### Styling Customization\n\nThe only public CSS custom property of the tree is `--mds-tree-line-clamp`, the number of lines a label keeps with `truncate=\"all\"` (2 by default). The colours of the labels, branches and toggles, their spacing and the transitions follow the semantic roles, so dark mode and high-contrast modes keep working: shape the tree with its props (`appearance`, `toggle`, `toggle-position`, `truncate`, `actions`) instead. Set the property on the host element or a parent selector.\n\n```css\n.navigazione-laterale mds-tree {\n --mds-tree-line-clamp: 3;\n}\n```\n\nThe toggle of an open item takes its expanded colours, and the connectors of the branches follow the distance between the toggle and the label of every item.\n",
33795
+ "2. Pattern": "Correct and idiomatic ways to use the `<mds-tree>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Nested Hierarchy\n\nThe canonical form: the root-level `<mds-tree-item>` elements are direct children of `<mds-tree>`, and `<mds-tree-item>` elements placed inside other `<mds-tree-item>` elements build depth. The tree seeds `depth = 0` on direct children, which drops their branch connector lines; nested items are indented by their nesting.\n\n```html\n<mds-tree>\n <mds-tree-item label=\"Direzione generale\">\n <mds-tree-item label=\"Segreteria\">\n <mds-tree-item label=\"Protocollo\"></mds-tree-item>\n <mds-tree-item label=\"Archivio\"></mds-tree-item>\n </mds-tree-item>\n <mds-tree-item label=\"Risorse umane\"></mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n```\n\n#### Flat List\n\nRoot-level nodes with no nesting are valid too, every `<mds-tree-item>` a direct child of `<mds-tree>`. With no branch to open the tree reads as a plain list.\n\n```html\n<mds-tree>\n <mds-tree-item label=\"Bacheca\"></mds-tree-item>\n <mds-tree-item label=\"Documenti\"></mds-tree-item>\n <mds-tree-item label=\"Impostazioni\"></mds-tree-item>\n</mds-tree>\n```\n\n#### Programmatic Expand / Collapse\n\nChange `expanded` on `<mds-tree>` at runtime to open or close the entire hierarchy at once. This cascades to all descendant items except those marked `async`, also when `expanded` is set in the markup; to start with a single branch open set `expanded` on that item instead.\n\n```html\n<!-- A branch expanded on mount -->\n<mds-tree id=\"albero-pratiche\">\n <mds-tree-item label=\"Pratiche in corso\" expanded>\n <mds-tree-item label=\"Pratica 001/2025\"></mds-tree-item>\n <mds-tree-item label=\"Pratica 002/2025\"></mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n\n<script>\n // Open or close the whole hierarchy later\n document.getElementById('albero-pratiche').expanded = true;\n</script>\n```\n\n#### Folder Toggle Style\n\nUse `toggle=\"folder\"` for file-explorer metaphors. The toggle icon switches between a closed and open folder glyph when the item is expanded or collapsed.\n\n```html\n<mds-tree toggle=\"folder\" actions=\"visible\">\n <mds-tree-item label=\"Fascicoli\">\n <mds-tree-item label=\"2025\">\n <mds-tree-item label=\"Fascicolo 001\"></mds-tree-item>\n <mds-tree-item label=\"Fascicolo 002\"></mds-tree-item>\n </mds-tree-item>\n <mds-tree-item label=\"2024\">\n <mds-tree-item label=\"Fascicolo 099\"></mds-tree-item>\n </mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n```\n\n#### Right-Positioned Toggle for Navigation Menus\n\nSet `toggle-position=\"right\"` and `appearance=\"none\"` for a flat navigation-menu look where the expand chevron sits at the trailing edge of the row.\n\n```html\n<mds-tree toggle=\"chevron\" toggle-position=\"right\" appearance=\"none\">\n <mds-tree-item label=\"Protocollazione documenti\">\n <mds-tree-item label=\"Nuovo protocollo in arrivo\"></mds-tree-item>\n <mds-tree-item label=\"Nuovo protocollo in partenza\"></mds-tree-item>\n </mds-tree-item>\n <mds-tree-item label=\"Gestione allegati\">\n <mds-tree-item label=\"Scansione multipla\"></mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n```\n\n#### Per-Item Actions via the `action` Slot\n\nSlot `<mds-button>` or `<mds-icon>` elements into each `<mds-tree-item>` with `slot=\"action\"`. Use `actions=\"auto\"` (default) to reveal them on hover, or `actions=\"visible\"` to always show them.\n\n```html\n<mds-tree actions=\"auto\">\n <mds-tree-item label=\"Relazione annuale 2025\">\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/download\"\n variant=\"dark\"\n tone=\"text\"\n title=\"Scarica\"\n ></mds-button>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/more-vert\"\n variant=\"dark\"\n tone=\"text\"\n title=\"Altre opzioni\"\n ></mds-button>\n <mds-tree-item label=\"Capitolo 1\"></mds-tree-item>\n <mds-tree-item label=\"Capitolo 2\"></mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n```\n\n#### Listening to Expand and Collapse Events\n\n`<mds-tree-item>` emits `mdsTreeItemCollapse` when it closes, and `mdsTreeItemExpand` only when an item marked `async` is asked to open (see below): opening a regular item emits nothing. Both events bubble, so one listener on the tree catches them. Listen via `addEventListener` - do not rely on native `change` / `click` bubbling through shadow DOM.\n\n```html\n<mds-tree id=\"albero-categorie\">\n <mds-tree-item label=\"Categoria A\">\n <mds-tree-item label=\"Sottocategoria A1\"></mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n\n<script>\n // emitted only by items marked async\n document.getElementById('albero-categorie').addEventListener('mdsTreeItemExpand', (event) => {\n console.log('espanso:', event.detail.element.label);\n });\n\n document.getElementById('albero-categorie').addEventListener('mdsTreeItemCollapse', (event) => {\n console.log('collassato:', event.detail.element.label);\n });\n</script>\n```\n\n#### Async Lazy-Loading Branches\n\nMark a `<mds-tree-item>` with `async` when its children must be fetched on demand. The item shows a loading spinner on click and emits `mdsTreeItemExpand`. Resolve the branch by calling `element.expand()` on the item once data is ready, then remove `async` so that reopening the branch later does not fetch it again. An item looks for child items only when it first renders: one that has none then shows no toggle (and no spinner), and children appended later do not add it.\n\n```html\n<mds-tree>\n <mds-tree-item label=\"Comune di Rimini\" icon=\"mgg/historic-building\">\n <mds-tree-item label=\"Ufficio\" async class=\"ufficio-item\" icon=\"mi/baseline/desk\">\n <!-- children appended by the script below -->\n </mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n\n<script>\n document.querySelector('.ufficio-item').addEventListener('mdsTreeItemExpand', async (event) => {\n const { element } = event.detail;\n if (!element.async) return;\n const children = await fetchChildren(element.label);\n children.forEach((nome) => {\n const item = document.createElement('mds-tree-item');\n item.label = nome;\n element.appendChild(item);\n });\n element.expand();\n element.async = false;\n });\n</script>\n```\n\n#### Icon on Individual Items\n\nUse the `icon` prop on `<mds-tree-item>` to show a glyph next to the label. Reference icons by their slug from the Magma icon library.\n\n```html\n<mds-tree toggle=\"chevron\">\n <mds-tree-item label=\"Comune di Rimini\" icon=\"mgg/historic-building\">\n <mds-tree-item label=\"Sindaco\" icon=\"mdi/handshake\">\n <mds-tree-item label=\"Segretario generale\" icon=\"mi/baseline/draw\"></mds-tree-item>\n </mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n```\n\n#### Styling Customization\n\nThe only public CSS custom property of the tree is `--mds-tree-line-clamp`, the number of lines a label keeps with `truncate=\"all\"` (2 by default). The colours of the labels, branches and toggles, their spacing and the transitions follow the semantic roles, so dark mode and high-contrast modes keep working: shape the tree with its props (`appearance`, `toggle`, `toggle-position`, `truncate`, `actions`) instead. Set the property on the host element or a parent selector.\n\n```css\n.navigazione-laterale mds-tree {\n --mds-tree-line-clamp: 3;\n}\n```\n\nThe toggle of an open item takes its expanded colours, and the connectors of the branches follow the distance between the toggle and the label of every item.\n",
33540
33796
  "3. Antipattern": "Common incorrect uses of `<mds-tree>`. 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/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Put Non-`mds-tree-item` Elements Directly in `<mds-tree>`\n\nThe default slot of `<mds-tree>` accepts only `<mds-tree-item>` elements. Placing raw HTML or other components as direct children breaks depth seeding and compound communication.\n\n```html\n<!-- INCORRECT -->\n<mds-tree>\n <li>Voce uno</li>\n <li>Voce due</li>\n</mds-tree>\n\n<!-- CORRECT -->\n<mds-tree>\n <mds-tree-item label=\"Voce uno\"></mds-tree-item>\n <mds-tree-item label=\"Voce due\"></mds-tree-item>\n</mds-tree>\n```\n\n#### Do Not Slot `<mds-tree-item>` Outside `<mds-tree>`\n\n`<mds-tree-item>` is a compound child and depends on `<mds-tree>` for depth seeding and prop cascading. Using it standalone produces undefined indentation and no toggle coordination.\n\n```html\n<!-- INCORRECT -->\n<div class=\"menu\">\n <mds-tree-item label=\"Impostazioni\">\n <mds-tree-item label=\"Profilo\"></mds-tree-item>\n </mds-tree-item>\n</div>\n\n<!-- CORRECT -->\n<mds-tree>\n <mds-tree-item label=\"Impostazioni\">\n <mds-tree-item label=\"Profilo\"></mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n```\n\n#### Do Not Use the `action` Slot on `<mds-tree>` Itself\n\nThe `action` slot is defined on `<mds-tree-item>`, not on `<mds-tree>`. Placing content with `slot=\"action\"` on the root container has no effect; the slot is silently discarded.\n\n```html\n<!-- INCORRECT -->\n<mds-tree>\n <mds-button slot=\"action\" icon=\"mi/baseline/add\" title=\"Aggiungi\"></mds-button>\n <mds-tree-item label=\"Documenti\"></mds-tree-item>\n</mds-tree>\n\n<!-- CORRECT -->\n<mds-tree>\n <mds-tree-item label=\"Documenti\">\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/add\"\n variant=\"dark\"\n tone=\"text\"\n title=\"Aggiungi\"\n ></mds-button>\n </mds-tree-item>\n</mds-tree>\n```\n\n#### Do Not Listen for Native `click` or `change` to Detect Expand/Collapse\n\nA native `click` tells you neither which item changed nor whether it opened or closed. Use the documented events emitted by `<mds-tree-item>`: `mdsTreeItemCollapse` when an item closes, `mdsTreeItemExpand` when an item marked `async` is asked to open.\n\n```html\n<!-- INCORRECT -->\n<mds-tree id=\"albero\">\n <mds-tree-item label=\"Sezione A\">\n <mds-tree-item label=\"Voce 1\"></mds-tree-item>\n </mds-tree-item>\n</mds-tree>\n\n<script>\n // unreliable - a click says nothing about the expanded state\n document.getElementById('albero').addEventListener('click', handler);\n</script>\n\n<!-- CORRECT -->\n<script>\n document.getElementById('albero').addEventListener('mdsTreeItemCollapse', (event) => {\n console.log('collassato:', event.detail.element.label);\n });\n</script>\n```\n\n#### Do Not Set `expanded=\"false\"` to Collapse\n\nStencil reads the exact string `\"false\"` as `false`, but the attribute stays on the element, where attribute selectors and presence checks (`hasAttribute('expanded')`) still read the tree as expanded. Remove the attribute (or set the prop to `undefined`) to collapse.\n\n```html\n<!-- INCORRECT -->\n<mds-tree expanded=\"false\">\n <mds-tree-item label=\"Sezione\"></mds-tree-item>\n</mds-tree>\n\n<!-- CORRECT -->\n<mds-tree>\n <mds-tree-item label=\"Sezione\"></mds-tree-item>\n</mds-tree>\n```\n\n#### Do Not Use Undocumented `::part()` Targets or `>>>` to Style Internals\n\nThe supported customization surface for `<mds-tree>` is its props and its public `--mds-tree-line-clamp` CSS custom property. Shadow-DOM piercing (`>>>`, `/deep/`) is not supported and `<mds-tree>` exposes no `::part()`. Coupling to internal selectors will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-tree >>> .header {\n background: red;\n}\n\n/* CORRECT */\nmds-tree {\n --mds-tree-line-clamp: 3;\n}\n```\n\n#### Do Not Wrap `<mds-tree-item>` in an Extra Div to Add Spacing\n\nInserting wrapper elements breaks the compound slot protocol - `<mds-tree>` communicates with items via `querySelectorAll` and slot assignment, and wrappers interrupt both. Keep the items as direct children: the tree sets their spacing itself, and it has no public CSS custom property for it.\n\n```html\n<!-- INCORRECT -->\n<mds-tree>\n <div style=\"margin-bottom: 8px;\">\n <mds-tree-item label=\"Categoria A\"></mds-tree-item>\n </div>\n <div style=\"margin-bottom: 8px;\">\n <mds-tree-item label=\"Categoria B\"></mds-tree-item>\n </div>\n</mds-tree>\n\n<!-- CORRECT -->\n<mds-tree>\n <mds-tree-item label=\"Categoria A\"></mds-tree-item>\n <mds-tree-item label=\"Categoria B\"></mds-tree-item>\n</mds-tree>\n```\n"
33541
33797
  },
33542
33798
  "props": [
@@ -34017,7 +34273,8 @@
34017
34273
  "states": [],
34018
34274
  "dependents": [],
34019
34275
  "dependencies": [],
34020
- "dependencyGraph": {}
34276
+ "dependencyGraph": {},
34277
+ "storybook": "ui-tree--docs"
34021
34278
  },
34022
34279
  {
34023
34280
  "filePath": "src/components/mds-tree-item/mds-tree-item.tsx",
@@ -34688,7 +34945,8 @@
34688
34945
  "mds-icon",
34689
34946
  "mds-text"
34690
34947
  ]
34691
- }
34948
+ },
34949
+ "storybook": "ui-tree-tree-item--docs"
34692
34950
  },
34693
34951
  {
34694
34952
  "filePath": "src/components/mds-url-view/mds-url-view.tsx",
@@ -34898,7 +35156,8 @@
34898
35156
  "mds-icon",
34899
35157
  "mds-text"
34900
35158
  ]
34901
- }
35159
+ },
35160
+ "storybook": "ui-url-view--docs"
34902
35161
  },
34903
35162
  {
34904
35163
  "filePath": "src/components/mds-usage/mds-usage.tsx",
@@ -35090,7 +35349,8 @@
35090
35349
  "mds-icon",
35091
35350
  "mds-text"
35092
35351
  ]
35093
- }
35352
+ },
35353
+ "storybook": "ui-usage--docs"
35094
35354
  },
35095
35355
  {
35096
35356
  "filePath": "src/components/mds-video-wall/mds-video-wall.tsx",
@@ -35405,7 +35665,8 @@
35405
35665
  "states": [],
35406
35666
  "dependents": [],
35407
35667
  "dependencies": [],
35408
- "dependencyGraph": {}
35668
+ "dependencyGraph": {},
35669
+ "storybook": "ui-video-wall--docs"
35409
35670
  },
35410
35671
  {
35411
35672
  "filePath": "src/components/mds-zero/mds-zero.tsx",
@@ -35483,7 +35744,8 @@
35483
35744
  "states": [],
35484
35745
  "dependents": [],
35485
35746
  "dependencies": [],
35486
- "dependencyGraph": {}
35747
+ "dependencyGraph": {},
35748
+ "storybook": "ui-zero--docs"
35487
35749
  }
35488
35750
  ],
35489
35751
  "typeLibrary": {
@@ -36227,5 +36489,6 @@
36227
36489
  "docstring": "",
36228
36490
  "path": "src/components/mds-video-wall/meta/types.ts"
36229
36491
  }
36230
- }
36492
+ },
36493
+ "storybook": "https://magma-design-system.github.io/magma/storybook/"
36231
36494
  }