@maggioli-design-system/magma 2.0.0-beta.3 → 2.0.0-beta.5
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.
- package/README.md +35 -3
- package/dist/cjs/date-B28IitWe.js +24 -0
- package/dist/cjs/floating-controller-Cd_vNLLD.js +369 -0
- package/dist/cjs/floating-ui.dom-DflSHZIo.js +1688 -0
- package/dist/cjs/form-DTCBh5WK.js +22 -0
- package/dist/cjs/index--6wz7eWi.js +5183 -0
- package/dist/cjs/index.cjs.js +17 -0
- package/dist/cjs/keyboard-manager-C_Eaxw-C.js +52 -0
- package/dist/cjs/loader.cjs.js +2 -2
- package/dist/cjs/locale-CB5_Z7PE.js +816 -0
- package/dist/cjs/magma-components.cjs.js +31 -4
- package/dist/cjs/mds-accordion-item.cjs.entry.js +7 -28
- package/dist/cjs/mds-accordion-timer-item.cjs.entry.js +8 -17
- package/dist/cjs/mds-accordion-timer.cjs.entry.js +3 -3
- package/dist/cjs/mds-accordion.cjs.entry.js +5 -22
- package/dist/cjs/mds-author.cjs.entry.js +9 -4
- package/dist/cjs/mds-avatar-stack-item.cjs.entry.js +2 -2
- package/dist/cjs/mds-avatar-stack.cjs.entry.js +5 -4
- package/dist/cjs/mds-avatar.cjs.entry.js +8 -21
- package/dist/cjs/mds-badge.cjs.entry.js +5 -26
- package/dist/cjs/mds-banner_3.cjs.entry.js +35 -70
- package/dist/cjs/mds-benchmark-bar.cjs.entry.js +2 -2
- package/dist/cjs/mds-bibliography.cjs.entry.js +2 -2
- package/dist/cjs/mds-breadcrumb-item.cjs.entry.js +3 -3
- package/dist/cjs/mds-breadcrumb.cjs.entry.js +7 -15
- package/dist/cjs/mds-button-dropdown.cjs.entry.js +3 -3
- package/dist/cjs/mds-button-group.cjs.entry.js +3 -3
- package/dist/cjs/mds-button_3.cjs.entry.js +10 -32
- package/dist/cjs/mds-calendar_2.cjs.entry.js +123 -102
- package/dist/cjs/mds-card-content.cjs.entry.js +2 -2
- package/dist/cjs/mds-card-footer.cjs.entry.js +2 -2
- package/dist/cjs/mds-card-header.cjs.entry.js +9 -4
- package/dist/cjs/mds-card-media.cjs.entry.js +2 -2
- package/dist/cjs/mds-card.cjs.entry.js +4 -21
- package/dist/cjs/mds-details.cjs.entry.js +8 -18
- package/dist/cjs/mds-dropdown.cjs.entry.js +184 -58
- package/dist/cjs/mds-emoji.cjs.entry.js +301 -181
- package/dist/cjs/mds-entity.cjs.entry.js +11 -23
- package/dist/cjs/mds-file-preview.cjs.entry.js +8 -36
- package/dist/cjs/mds-file.cjs.entry.js +6 -34
- package/dist/cjs/mds-filter-item.cjs.entry.js +6 -25
- package/dist/cjs/mds-filter.cjs.entry.js +19 -32
- package/dist/cjs/mds-header-bar.cjs.entry.js +11 -27
- package/dist/cjs/mds-header.cjs.entry.js +8 -22
- package/dist/cjs/mds-horizontal-scroll.cjs.entry.js +2 -2
- package/dist/cjs/mds-hr.cjs.entry.js +4 -17
- package/dist/cjs/mds-img.cjs.entry.js +8 -16
- package/dist/cjs/mds-input-date-range-preselection.cjs.entry.js +2 -2
- package/dist/cjs/mds-input-date-range.cjs.entry.js +57 -43
- package/dist/cjs/mds-input-date.cjs.entry.js +14 -44
- package/dist/cjs/mds-input-field.cjs.entry.js +42 -6
- package/dist/cjs/mds-input-otp.cjs.entry.js +37 -3
- package/dist/cjs/mds-input-range.cjs.entry.js +9 -29
- package/dist/cjs/mds-input-select.cjs.entry.js +11 -41
- package/dist/cjs/mds-input-switch_2.cjs.entry.js +19 -55
- package/dist/cjs/mds-input-tip_2.cjs.entry.js +8 -40
- package/dist/cjs/mds-input-upload.cjs.entry.js +34 -36
- package/dist/cjs/mds-input.cjs.entry.js +23 -52
- package/dist/cjs/mds-keyboard-key.cjs.entry.js +5 -14
- package/dist/cjs/mds-keyboard.cjs.entry.js +5 -25
- package/dist/cjs/mds-kpi-item.cjs.entry.js +12 -25
- package/dist/cjs/mds-kpi.cjs.entry.js +2 -2
- package/dist/cjs/mds-label.cjs.entry.js +7 -29
- package/dist/cjs/mds-list-item.cjs.entry.js +4 -13
- package/dist/cjs/mds-list.cjs.entry.js +1 -1
- package/dist/cjs/mds-mention.cjs.entry.js +38 -4
- package/dist/cjs/mds-modal.cjs.entry.js +54 -47
- package/dist/cjs/mds-note.cjs.entry.js +7 -35
- package/dist/cjs/mds-notification.cjs.entry.js +12 -14
- package/dist/cjs/mds-paginator-item.cjs.entry.js +5 -20
- package/dist/cjs/mds-paginator.cjs.entry.js +27 -32
- package/dist/cjs/mds-policy-ai.cjs.entry.js +5 -15
- package/dist/cjs/mds-pref-animation.cjs.entry.js +7 -23
- package/dist/cjs/mds-pref-consumption.cjs.entry.js +7 -23
- package/dist/cjs/mds-pref-contrast.cjs.entry.js +10 -24
- package/dist/cjs/mds-pref-language-item.cjs.entry.js +27 -15
- package/dist/cjs/mds-pref-language.cjs.entry.js +38 -28
- package/dist/cjs/mds-pref-mode.cjs.entry.js +273 -0
- package/dist/cjs/mds-pref-theme-item.cjs.entry.js +43 -0
- package/dist/cjs/mds-pref-theme.cjs.entry.js +147 -230
- package/dist/cjs/mds-pref.cjs.entry.js +40 -17
- package/dist/cjs/mds-price-table-features-cell.cjs.entry.js +4 -25
- package/dist/cjs/mds-price-table-features-row.cjs.entry.js +4 -25
- package/dist/cjs/mds-price-table-features.cjs.entry.js +4 -25
- package/dist/cjs/mds-price-table-header.cjs.entry.js +2 -2
- package/dist/cjs/mds-price-table-list-item.cjs.entry.js +3 -3
- package/dist/cjs/mds-price-table-list.cjs.entry.js +4 -25
- package/dist/cjs/mds-price-table.cjs.entry.js +2 -2
- package/dist/cjs/mds-progress_2.cjs.entry.js +7 -33
- package/dist/cjs/mds-push-notification-item.cjs.entry.js +16 -39
- package/dist/cjs/mds-push-notification.cjs.entry.js +7 -20
- package/dist/cjs/mds-quote.cjs.entry.js +4 -13
- package/dist/cjs/mds-radial-menu-item.cjs.entry.js +3 -3
- package/dist/cjs/mds-radial-menu.cjs.entry.js +7 -6
- package/dist/cjs/mds-separator.cjs.entry.js +4 -21
- package/dist/cjs/mds-status-bar.cjs.entry.js +4 -25
- package/dist/cjs/mds-stepper-bar-item.cjs.entry.js +14 -25
- package/dist/cjs/mds-stepper-bar.cjs.entry.js +21 -12
- package/dist/cjs/mds-tab-bar-item.cjs.entry.js +6 -27
- package/dist/cjs/mds-tab-bar.cjs.entry.js +5 -26
- package/dist/cjs/mds-tab_2.cjs.entry.js +14 -47
- package/dist/cjs/mds-table-body.cjs.entry.js +4 -13
- package/dist/cjs/mds-table-footer.cjs.entry.js +4 -13
- package/dist/cjs/mds-table-header-cell.cjs.entry.js +4 -13
- package/dist/cjs/mds-table-header.cjs.entry.js +19 -31
- package/dist/cjs/mds-table-row.cjs.entry.js +20 -29
- package/dist/cjs/mds-table.cjs.entry.js +60 -50
- package/dist/cjs/mds-text.cjs.entry.js +36 -21
- package/dist/cjs/mds-toast.cjs.entry.js +10 -27
- package/dist/cjs/mds-tooltip.cjs.entry.js +16 -27
- package/dist/cjs/mds-tree-item.cjs.entry.js +12 -14
- package/dist/cjs/mds-tree.cjs.entry.js +12 -6
- package/dist/cjs/mds-url-view.cjs.entry.js +21 -41
- package/dist/cjs/mds-usage.cjs.entry.js +5 -33
- package/dist/cjs/mds-video-wall.cjs.entry.js +8 -4
- package/dist/cjs/mds-zero.cjs.entry.js +4 -25
- package/dist/cjs/preference-eJcbLLAn.js +389 -0
- package/dist/cjs/slot-RmXfgH4P.js +69 -0
- package/dist/collection/collection-manifest.json +3 -3
- package/dist/collection/common/date.js +9 -1
- package/dist/collection/common/floating-controller.js +175 -9
- package/dist/collection/common/form.js +18 -0
- package/dist/collection/common/keyboard-manager.js +5 -5
- package/dist/collection/common/locale.js +9 -31
- package/dist/collection/common/preference.js +83 -59
- package/dist/collection/common/slot.js +14 -1
- package/dist/collection/common/yugop/random-text.js +12 -3
- package/dist/collection/components/mds-accordion/mds-accordion.css +9 -65
- package/dist/collection/components/mds-accordion/mds-accordion.js +3 -27
- package/dist/collection/components/mds-accordion-item/mds-accordion-item.css +63 -81
- package/dist/collection/components/mds-accordion-item/mds-accordion-item.js +2 -31
- package/dist/collection/components/mds-accordion-timer/mds-accordion-timer.css +2 -26
- package/dist/collection/components/mds-accordion-timer-item/mds-accordion-timer-item.css +50 -36
- package/dist/collection/components/mds-accordion-timer-item/mds-accordion-timer-item.js +2 -16
- package/dist/collection/components/mds-author/mds-author.css +4 -0
- package/dist/collection/components/mds-author/mds-author.js +14 -2
- package/dist/collection/components/mds-avatar/mds-avatar.css +125 -111
- package/dist/collection/components/mds-avatar/mds-avatar.js +6 -21
- package/dist/collection/components/mds-avatar-stack/mds-avatar-stack.css +12 -84
- package/dist/collection/components/mds-avatar-stack/mds-avatar-stack.js +3 -2
- package/dist/collection/components/mds-avatar-stack-item/mds-avatar-stack-item.css +6 -24
- package/dist/collection/components/mds-badge/mds-badge.css +168 -155
- package/dist/collection/components/mds-badge/mds-badge.js +2 -31
- package/dist/collection/components/mds-banner/mds-banner.css +149 -192
- package/dist/collection/components/mds-banner/mds-banner.js +10 -58
- package/dist/collection/components/mds-bibliography/mds-bibliography.css +6 -24
- package/dist/collection/components/mds-breadcrumb/mds-breadcrumb.css +6 -70
- package/dist/collection/components/mds-breadcrumb/mds-breadcrumb.js +2 -37
- package/dist/collection/components/mds-breadcrumb-item/mds-breadcrumb-item.css +15 -67
- package/dist/collection/components/mds-button/mds-button.css +285 -333
- package/dist/collection/components/mds-button/mds-button.js +4 -24
- package/dist/collection/components/mds-button-dropdown/mds-button-dropdown.css +24 -34
- package/dist/collection/components/mds-button-dropdown/mds-button-dropdown.js +1 -1
- package/dist/collection/components/mds-button-group/mds-button-group.css +13 -4
- package/dist/collection/components/mds-button-group/mds-button-group.js +2 -2
- package/dist/collection/components/mds-calendar/mds-calendar.css +13 -69
- package/dist/collection/components/mds-calendar/mds-calendar.js +150 -127
- package/dist/collection/components/mds-calendar-cell/mds-calendar-cell.css +88 -299
- package/dist/collection/components/mds-card/mds-card.css +11 -35
- package/dist/collection/components/mds-card/mds-card.js +2 -22
- package/dist/collection/components/mds-card-content/mds-card-content.css +1 -0
- package/dist/collection/components/mds-card-footer/mds-card-footer.css +1 -0
- package/dist/collection/components/mds-card-header/mds-card-header.css +5 -0
- package/dist/collection/components/mds-card-header/mds-card-header.js +14 -2
- package/dist/collection/components/mds-card-media/mds-card-media.css +1 -1
- package/dist/collection/components/mds-chip/mds-chip.css +317 -278
- package/dist/collection/components/mds-chip/mds-chip.js +19 -61
- package/dist/collection/components/mds-details/mds-details.css +52 -28
- package/dist/collection/components/mds-details/mds-details.js +4 -16
- package/dist/collection/components/mds-dropdown/mds-dropdown.css +102 -121
- package/dist/collection/components/mds-dropdown/mds-dropdown.js +179 -59
- package/dist/collection/components/mds-emoji/asset/mia.svg +3 -3
- package/dist/collection/components/mds-emoji/mds-emoji.css +15 -179
- package/dist/collection/components/mds-emoji/mds-emoji.js +297 -177
- package/dist/collection/components/mds-entity/mds-entity.css +25 -76
- package/dist/collection/components/mds-entity/mds-entity.js +13 -24
- package/dist/collection/components/mds-file/mds-file.css +103 -79
- package/dist/collection/components/mds-file/mds-file.js +2 -56
- package/dist/collection/components/mds-file-preview/mds-file-preview.css +277 -218
- package/dist/collection/components/mds-file-preview/mds-file-preview.js +4 -62
- package/dist/collection/components/mds-filter/mds-filter.css +66 -78
- package/dist/collection/components/mds-filter/mds-filter.js +16 -33
- package/dist/collection/components/mds-filter-item/mds-filter-item.css +73 -53
- package/dist/collection/components/mds-filter-item/mds-filter-item.js +2 -29
- package/dist/collection/components/mds-header/mds-header.css +15 -68
- package/dist/collection/components/mds-header/mds-header.js +5 -22
- package/dist/collection/components/mds-header-bar/mds-header-bar.css +60 -31
- package/dist/collection/components/mds-header-bar/mds-header-bar.js +9 -28
- package/dist/collection/components/mds-help/mds-help.css +1 -19
- package/dist/collection/components/mds-horizontal-scroll/mds-horizontal-scroll.css +13 -104
- package/dist/collection/components/mds-hr/mds-hr.css +6 -18
- package/dist/collection/components/mds-hr/mds-hr.js +2 -21
- package/dist/collection/components/mds-icon/services/icons-set.service.js +16 -0
- package/dist/collection/components/mds-img/mds-img.css +12 -48
- package/dist/collection/components/mds-img/mds-img.js +5 -36
- package/dist/collection/components/mds-input/mds-input.css +120 -158
- package/dist/collection/components/mds-input/mds-input.js +33 -65
- package/dist/collection/components/mds-input-date/mds-input-date.css +107 -124
- package/dist/collection/components/mds-input-date/mds-input-date.js +49 -62
- package/dist/collection/components/mds-input-date-range/mds-input-date-range.css +100 -90
- package/dist/collection/components/mds-input-date-range/mds-input-date-range.js +77 -62
- package/dist/collection/components/mds-input-date-range-preselection/mds-input-date-range-preselection.css +19 -73
- package/dist/collection/components/mds-input-field/mds-input-field.css +33 -45
- package/dist/collection/components/mds-input-field/mds-input-field.js +41 -4
- package/dist/collection/components/mds-input-otp/mds-input-otp.js +38 -2
- package/dist/collection/components/mds-input-range/mds-input-range.css +61 -19
- package/dist/collection/components/mds-input-range/mds-input-range.js +7 -31
- package/dist/collection/components/mds-input-select/mds-input-select.css +123 -156
- package/dist/collection/components/mds-input-select/mds-input-select.js +28 -61
- package/dist/collection/components/mds-input-switch/mds-input-switch.css +91 -250
- package/dist/collection/components/mds-input-switch/mds-input-switch.js +12 -63
- package/dist/collection/components/mds-input-tip/mds-input-tip.css +45 -31
- package/dist/collection/components/mds-input-tip/mds-input-tip.js +2 -16
- package/dist/collection/components/mds-input-tip-item/mds-input-tip-item.css +84 -56
- package/dist/collection/components/mds-input-tip-item/mds-input-tip-item.js +3 -54
- package/dist/collection/components/mds-input-upload/mds-input-upload.css +26 -37
- package/dist/collection/components/mds-input-upload/mds-input-upload.js +30 -51
- package/dist/collection/components/mds-keyboard/mds-keyboard.css +32 -126
- package/dist/collection/components/mds-keyboard/mds-keyboard.js +2 -46
- package/dist/collection/components/mds-keyboard-key/mds-keyboard-key.css +4 -28
- package/dist/collection/components/mds-keyboard-key/mds-keyboard-key.js +1 -37
- package/dist/collection/components/mds-kpi/mds-kpi.css +6 -11
- package/dist/collection/components/mds-kpi-item/mds-kpi-item.css +103 -40
- package/dist/collection/components/mds-kpi-item/mds-kpi-item.js +10 -27
- package/dist/collection/components/mds-label/mds-label.css +265 -354
- package/dist/collection/components/mds-label/mds-label.js +3 -54
- package/dist/collection/components/mds-list-item/mds-list-item.css +3 -9
- package/dist/collection/components/mds-list-item/mds-list-item.js +2 -16
- package/dist/collection/components/mds-mention/mds-mention.css +19 -10
- package/dist/collection/components/mds-mention/mds-mention.js +62 -2
- package/dist/collection/components/mds-modal/mds-modal.css +71 -101
- package/dist/collection/components/mds-modal/mds-modal.js +72 -45
- package/dist/collection/components/mds-note/mds-note.css +220 -198
- package/dist/collection/components/mds-note/mds-note.js +3 -61
- package/dist/collection/components/mds-notification/mds-notification.css +55 -89
- package/dist/collection/components/mds-notification/mds-notification.js +9 -16
- package/dist/collection/components/mds-paginator/mds-paginator.css +71 -35
- package/dist/collection/components/mds-paginator/mds-paginator.js +24 -37
- package/dist/collection/components/mds-paginator-item/mds-paginator-item.css +78 -96
- package/dist/collection/components/mds-paginator-item/mds-paginator-item.js +2 -24
- package/dist/collection/components/mds-policy-ai/mds-policy-ai.css +9 -9
- package/dist/collection/components/mds-policy-ai/mds-policy-ai.js +1 -38
- package/dist/collection/components/mds-pref/mds-pref.js +40 -40
- package/dist/collection/components/mds-pref-animation/mds-pref-animation.css +50 -6
- package/dist/collection/components/mds-pref-animation/mds-pref-animation.js +4 -47
- package/dist/collection/components/mds-pref-consumption/mds-pref-consumption.css +12 -12
- package/dist/collection/components/mds-pref-consumption/mds-pref-consumption.js +4 -47
- package/dist/collection/components/mds-pref-contrast/mds-pref-contrast.css +4 -4
- package/dist/collection/components/mds-pref-contrast/mds-pref-contrast.js +7 -48
- package/dist/collection/components/mds-pref-language/mds-pref-language.css +3 -3
- package/dist/collection/components/mds-pref-language/mds-pref-language.js +35 -46
- package/dist/collection/components/mds-pref-language-item/mds-pref-language-item.js +24 -38
- package/dist/collection/components/mds-pref-mode/mds-pref-mode.css +79 -0
- package/dist/collection/components/mds-pref-mode/mds-pref-mode.js +372 -0
- package/dist/collection/components/mds-pref-mode/meta/dictionary.js +3 -0
- package/dist/collection/components/mds-pref-theme/mds-pref-theme.css +12 -77
- package/dist/collection/components/mds-pref-theme/mds-pref-theme.js +183 -239
- package/dist/collection/components/mds-pref-theme/meta/dictionary.js +2 -3
- package/dist/collection/components/mds-pref-theme-item/mds-pref-theme-item.css +70 -0
- package/dist/collection/components/mds-pref-theme-item/mds-pref-theme-item.js +160 -0
- package/dist/collection/components/mds-price-table/mds-price-table.js +1 -1
- package/dist/collection/components/mds-price-table-features/mds-price-table-features.css +56 -47
- package/dist/collection/components/mds-price-table-features/mds-price-table-features.js +2 -31
- package/dist/collection/components/mds-price-table-features-cell/mds-price-table-features-cell.css +71 -67
- package/dist/collection/components/mds-price-table-features-cell/mds-price-table-features-cell.js +2 -31
- package/dist/collection/components/mds-price-table-features-row/mds-price-table-features-row.css +66 -42
- package/dist/collection/components/mds-price-table-features-row/mds-price-table-features-row.js +3 -28
- package/dist/collection/components/mds-price-table-header/mds-price-table-header.js +1 -1
- package/dist/collection/components/mds-price-table-list/mds-price-table-list.css +63 -25
- package/dist/collection/components/mds-price-table-list/mds-price-table-list.js +3 -28
- package/dist/collection/components/mds-price-table-list-item/mds-price-table-list-item.css +5 -31
- package/dist/collection/components/mds-price-table-list-item/mds-price-table-list-item.js +1 -1
- package/dist/collection/components/mds-progress/mds-progress.css +100 -94
- package/dist/collection/components/mds-progress/mds-progress.js +2 -27
- package/dist/collection/components/mds-push-notification/mds-push-notification.css +7 -37
- package/dist/collection/components/mds-push-notification/mds-push-notification.js +2 -21
- package/dist/collection/components/mds-push-notification-item/mds-push-notification-item.css +172 -136
- package/dist/collection/components/mds-push-notification-item/mds-push-notification-item.js +13 -60
- package/dist/collection/components/mds-quote/mds-quote.css +2 -2
- package/dist/collection/components/mds-quote/mds-quote.js +2 -16
- package/dist/collection/components/mds-radial-menu/mds-radial-menu.css +6 -60
- package/dist/collection/components/mds-radial-menu/mds-radial-menu.js +3 -2
- package/dist/collection/components/mds-radial-menu-item/mds-radial-menu-item.css +1 -7
- package/dist/collection/components/mds-radial-menu-item/mds-radial-menu-item.js +1 -1
- package/dist/collection/components/mds-radial-progress/mds-radial-progress.css +24 -30
- package/dist/collection/components/mds-radial-progress/mds-radial-progress.js +3 -7
- package/dist/collection/components/mds-separator/mds-separator.css +12 -42
- package/dist/collection/components/mds-separator/mds-separator.js +2 -26
- package/dist/collection/components/mds-spinner/mds-spinner.css +3 -9
- package/dist/collection/components/mds-spinner/mds-spinner.js +2 -16
- package/dist/collection/components/mds-status-bar/mds-status-bar.css +13 -23
- package/dist/collection/components/mds-status-bar/mds-status-bar.js +2 -31
- package/dist/collection/components/mds-stepper-bar/mds-stepper-bar.css +8 -56
- package/dist/collection/components/mds-stepper-bar/mds-stepper-bar.js +18 -9
- package/dist/collection/components/mds-stepper-bar-item/mds-stepper-bar-item.css +68 -120
- package/dist/collection/components/mds-stepper-bar-item/mds-stepper-bar-item.js +10 -44
- package/dist/collection/components/mds-tab/mds-tab.css +85 -189
- package/dist/collection/components/mds-tab/mds-tab.js +5 -27
- package/dist/collection/components/mds-tab-bar/mds-tab-bar.css +54 -10
- package/dist/collection/components/mds-tab-bar/mds-tab-bar.js +2 -31
- package/dist/collection/components/mds-tab-bar-item/mds-tab-bar-item.css +62 -44
- package/dist/collection/components/mds-tab-bar-item/mds-tab-bar-item.js +2 -27
- package/dist/collection/components/mds-tab-item/mds-tab-item.css +22 -37
- package/dist/collection/components/mds-tab-item/mds-tab-item.js +23 -22
- package/dist/collection/components/mds-table/mds-table.css +86 -130
- package/dist/collection/components/mds-table/mds-table.js +57 -52
- package/dist/collection/components/mds-table-body/mds-table-body.css +54 -40
- package/dist/collection/components/mds-table-body/mds-table-body.js +2 -16
- package/dist/collection/components/mds-table-cell/mds-table-cell.css +62 -32
- package/dist/collection/components/mds-table-cell/mds-table-cell.js +2 -16
- package/dist/collection/components/mds-table-footer/mds-table-footer.css +44 -0
- package/dist/collection/components/mds-table-footer/mds-table-footer.js +2 -16
- package/dist/collection/components/mds-table-header/mds-table-header.css +44 -0
- package/dist/collection/components/mds-table-header/mds-table-header.js +17 -48
- package/dist/collection/components/mds-table-header-cell/mds-table-header-cell.css +47 -7
- package/dist/collection/components/mds-table-header-cell/mds-table-header-cell.js +3 -13
- package/dist/collection/components/mds-table-row/mds-table-row.css +67 -49
- package/dist/collection/components/mds-table-row/mds-table-row.js +19 -50
- package/dist/collection/components/mds-text/mds-text.css +18 -38
- package/dist/collection/components/mds-text/mds-text.js +23 -22
- package/dist/collection/components/mds-toast/mds-toast.css +99 -90
- package/dist/collection/components/mds-toast/mds-toast.js +8 -28
- package/dist/collection/components/mds-tooltip/mds-tooltip.css +68 -85
- package/dist/collection/components/mds-tooltip/mds-tooltip.js +12 -31
- package/dist/collection/components/mds-tree/mds-tree.css +20 -212
- package/dist/collection/components/mds-tree/mds-tree.js +10 -4
- package/dist/collection/components/mds-tree-item/mds-tree-item.css +146 -267
- package/dist/collection/components/mds-tree-item/mds-tree-item.js +7 -28
- package/dist/collection/components/mds-url-view/mds-url-view.css +59 -33
- package/dist/collection/components/mds-url-view/mds-url-view.js +17 -67
- package/dist/collection/components/mds-usage/mds-usage.css +80 -95
- package/dist/collection/components/mds-usage/mds-usage.js +2 -60
- package/dist/collection/components/mds-video-wall/mds-video-wall.css +11 -26
- package/dist/collection/components/mds-video-wall/mds-video-wall.js +11 -2
- package/dist/collection/components/mds-zero/mds-zero.css +56 -18
- package/dist/collection/components/mds-zero/mds-zero.js +2 -31
- package/dist/collection/event-detail/theme.js +1 -0
- package/dist/collection/type/preference.js +22 -3
- package/dist/components/index.d.ts +230 -0
- package/dist/components/index.js +1 -1
- package/dist/components/mds-accordion-item.js +1 -1
- package/dist/components/mds-accordion-timer-item.js +1 -1
- package/dist/components/mds-accordion-timer.js +1 -1
- package/dist/components/mds-accordion.js +1 -1
- package/dist/components/mds-author.js +1 -1
- package/dist/components/mds-avatar-stack-item.js +1 -1
- package/dist/components/mds-avatar-stack.js +1 -1
- package/dist/components/mds-avatar.js +1 -1
- package/dist/components/mds-badge.js +1 -1
- package/dist/components/mds-banner.js +1 -1
- package/dist/components/mds-benchmark-bar.js +1 -1
- package/dist/components/mds-bibliography.js +1 -1
- package/dist/components/mds-breadcrumb-item.js +1 -1
- package/dist/components/mds-breadcrumb.js +1 -1
- package/dist/components/mds-button-dropdown.js +1 -1
- package/dist/components/mds-button-group.js +1 -1
- package/dist/components/mds-button.js +1 -1
- package/dist/components/mds-calendar-cell.js +1 -1
- package/dist/components/mds-calendar.js +1 -1
- package/dist/components/mds-card-content.js +1 -1
- package/dist/components/mds-card-footer.js +1 -1
- package/dist/components/mds-card-header.js +1 -1
- package/dist/components/mds-card-media.js +1 -1
- package/dist/components/mds-card.js +1 -1
- package/dist/components/mds-chip.js +1 -1
- package/dist/components/mds-details.js +1 -1
- package/dist/components/mds-dropdown.js +1 -1
- package/dist/components/mds-emoji.js +3 -3
- package/dist/components/mds-entity.js +1 -1
- package/dist/components/mds-file-preview.js +1 -1
- package/dist/components/mds-file.js +3 -3
- package/dist/components/mds-filter-item.js +1 -1
- package/dist/components/mds-filter.js +1 -1
- package/dist/components/mds-header-bar.js +1 -1
- package/dist/components/mds-header.js +1 -1
- package/dist/components/mds-help.js +1 -1
- package/dist/components/mds-horizontal-scroll.js +1 -1
- package/dist/components/mds-hr.js +1 -1
- package/dist/components/mds-icon.js +1 -1
- package/dist/components/mds-img.js +1 -1
- package/dist/components/mds-input-date-range-preselection.js +1 -1
- package/dist/components/mds-input-date-range.js +1 -1
- package/dist/components/mds-input-date.js +1 -1
- package/dist/components/mds-input-field.js +1 -1
- package/dist/components/mds-input-otp.js +1 -1
- package/dist/components/mds-input-range.js +1 -1
- package/dist/components/mds-input-select.js +1 -1
- package/dist/components/mds-input-switch.js +1 -1
- package/dist/components/mds-input-tip-item.js +1 -1
- package/dist/components/mds-input-tip.js +1 -1
- package/dist/components/mds-input-upload.js +1 -1
- package/dist/components/mds-input.js +1 -1
- package/dist/components/mds-keyboard-key.js +1 -1
- package/dist/components/mds-keyboard.js +1 -1
- package/dist/components/mds-kpi-item.js +1 -1
- package/dist/components/mds-kpi.js +1 -1
- package/dist/components/mds-label.js +1 -1
- package/dist/components/mds-list-item.js +1 -1
- package/dist/components/mds-list.js +1 -1
- package/dist/components/mds-mention.js +1 -1
- package/dist/components/mds-modal.js +1 -1
- package/dist/components/mds-note.js +1 -1
- package/dist/components/mds-notification.js +1 -1
- package/dist/components/mds-paginator-item.js +1 -1
- package/dist/components/mds-paginator.js +1 -1
- package/dist/components/mds-policy-ai.js +1 -1
- package/dist/components/mds-pref-animation.js +1 -1
- package/dist/components/mds-pref-consumption.js +1 -1
- package/dist/components/mds-pref-contrast.js +1 -1
- package/dist/components/mds-pref-language-item.js +1 -1
- package/dist/components/mds-pref-language.js +1 -1
- package/dist/components/mds-pref-mode.d.ts +11 -0
- package/dist/components/mds-pref-mode.js +1 -0
- package/dist/components/mds-pref-theme-item.d.ts +11 -0
- package/dist/components/mds-pref-theme-item.js +1 -0
- package/dist/components/mds-pref-theme.js +1 -1
- package/dist/components/mds-pref.js +1 -1
- package/dist/components/mds-price-table-features-cell.js +1 -1
- package/dist/components/mds-price-table-features-row.js +1 -1
- package/dist/components/mds-price-table-features.js +1 -1
- package/dist/components/mds-price-table-header.js +1 -1
- package/dist/components/mds-price-table-list-item.js +1 -1
- package/dist/components/mds-price-table-list.js +1 -1
- package/dist/components/mds-price-table.js +1 -1
- package/dist/components/mds-progress.js +1 -1
- package/dist/components/mds-push-notification-item.js +1 -1
- package/dist/components/mds-push-notification.js +1 -1
- package/dist/components/mds-quote.js +1 -1
- package/dist/components/mds-radial-menu-item.js +1 -1
- package/dist/components/mds-radial-menu.js +1 -1
- package/dist/components/mds-radial-progress.js +1 -1
- package/dist/components/mds-separator.js +1 -1
- package/dist/components/mds-spinner.js +1 -1
- package/dist/components/mds-status-bar.js +1 -1
- package/dist/components/mds-stepper-bar-item.js +1 -1
- package/dist/components/mds-stepper-bar.js +1 -1
- package/dist/components/mds-tab-bar-item.js +1 -1
- package/dist/components/mds-tab-bar.js +1 -1
- package/dist/components/mds-tab-item.js +1 -1
- package/dist/components/mds-tab.js +1 -1
- package/dist/components/mds-table-body.js +1 -1
- package/dist/components/mds-table-cell.js +1 -1
- package/dist/components/mds-table-footer.js +1 -1
- package/dist/components/mds-table-header-cell.js +1 -1
- package/dist/components/mds-table-header.js +1 -1
- package/dist/components/mds-table-row.js +1 -1
- package/dist/components/mds-table.js +1 -1
- package/dist/components/mds-text.js +1 -1
- package/dist/components/mds-toast.js +1 -1
- package/dist/components/mds-tooltip.js +1 -1
- package/dist/components/mds-tree-item.js +1 -1
- package/dist/components/mds-tree.js +1 -1
- package/dist/components/mds-url-view.js +1 -1
- package/dist/components/mds-usage.js +1 -1
- package/dist/components/mds-video-wall.js +1 -1
- package/dist/components/mds-zero.js +1 -1
- package/dist/components/p--8aaJX-p.js +1 -0
- package/dist/components/p-A9TZf0Ii.js +1 -0
- package/dist/components/p-B14Ci2fO.js +1 -0
- package/dist/components/p-B2A_hlV2.js +1 -0
- package/dist/components/p-B9DJLgwr.js +1 -0
- package/dist/components/p-BH3bWzRT.js +1 -0
- package/dist/components/p-BJNK4p33.js +1 -0
- package/dist/components/p-BNHXZ-JR.js +1 -0
- package/dist/components/p-BSxuG1vZ.js +1 -0
- package/dist/components/p-BTHR4xXu.js +1 -0
- package/dist/components/p-BhFTcUD0.js +3 -0
- package/dist/components/p-BouRLCYL.js +1 -0
- package/dist/components/p-Bss3F51Q.js +5 -0
- package/dist/components/p-Bt4xX5ww.js +1 -0
- package/dist/components/p-C03KYHGv.js +1 -0
- package/dist/components/p-C58NKMEE.js +1 -0
- package/dist/components/p-CACEYk42.js +1 -0
- package/dist/components/p-CBLAz3_J.js +1 -0
- package/dist/components/p-CHAGzQT-.js +1 -0
- package/dist/components/p-CVgKDZPF.js +1 -0
- package/dist/components/p-CVpjH8Un.js +1 -0
- package/dist/components/p-Caksrfcd.js +1 -0
- package/dist/components/p-CatD1iUY.js +1 -0
- package/dist/components/p-CbufYCNj.js +1 -0
- package/dist/components/p-Cehcn85x.js +1 -0
- package/dist/components/p-CsgCQiHG.js +1 -0
- package/dist/components/p-CvIFS8oA.js +1 -0
- package/dist/components/p-D3-GP4KF.js +1 -0
- package/dist/components/p-D8I1RblC.js +1 -0
- package/dist/components/p-DLE5TNTp.js +1 -0
- package/dist/components/p-DaI5QqNu.js +1 -0
- package/dist/components/p-Deh5Aia-.js +1 -0
- package/dist/components/p-Dj_oN194.js +1 -0
- package/dist/components/p-DmELzfvf.js +1 -0
- package/dist/components/p-DtxB7DYE.js +1 -0
- package/dist/components/p-KRu9I7dw.js +1 -0
- package/dist/components/p-cBZsPiMJ.js +1 -0
- package/dist/components/p-sUKtonkE.js +8 -0
- package/dist/components/p-sqRs6oj4.js +1 -0
- package/dist/components/p-wq6nWuWE.js +1 -0
- package/dist/documentation.json +750 -1137
- package/dist/esm/date-CACEYk42.js +22 -0
- package/dist/esm/floating-controller-DVldZ5mh.js +366 -0
- package/dist/esm/floating-ui.dom-CHAGzQT-.js +1680 -0
- package/dist/esm/form-A9TZf0Ii.js +19 -0
- package/dist/esm/index-DIiEV39g.js +5149 -0
- package/dist/esm/index.js +17 -0
- package/dist/esm/keyboard-manager-KRu9I7dw.js +50 -0
- package/dist/esm/loader.js +3 -3
- package/dist/esm/locale-CbJbTW_c.js +814 -0
- package/dist/esm/magma-components.js +32 -5
- package/dist/esm/mds-accordion-item.entry.js +7 -28
- package/dist/esm/mds-accordion-timer-item.entry.js +8 -17
- package/dist/esm/mds-accordion-timer.entry.js +3 -3
- package/dist/esm/mds-accordion.entry.js +5 -22
- package/dist/esm/mds-author.entry.js +9 -4
- package/dist/esm/mds-avatar-stack-item.entry.js +2 -2
- package/dist/esm/mds-avatar-stack.entry.js +5 -4
- package/dist/esm/mds-avatar.entry.js +8 -21
- package/dist/esm/mds-badge.entry.js +5 -26
- package/dist/esm/mds-banner_3.entry.js +35 -70
- package/dist/esm/mds-benchmark-bar.entry.js +2 -2
- package/dist/esm/mds-bibliography.entry.js +2 -2
- package/dist/esm/mds-breadcrumb-item.entry.js +3 -3
- package/dist/esm/mds-breadcrumb.entry.js +7 -15
- package/dist/esm/mds-button-dropdown.entry.js +3 -3
- package/dist/esm/mds-button-group.entry.js +3 -3
- package/dist/esm/mds-button_3.entry.js +10 -32
- package/dist/esm/mds-calendar_2.entry.js +123 -102
- package/dist/esm/mds-card-content.entry.js +2 -2
- package/dist/esm/mds-card-footer.entry.js +2 -2
- package/dist/esm/mds-card-header.entry.js +9 -4
- package/dist/esm/mds-card-media.entry.js +2 -2
- package/dist/esm/mds-card.entry.js +4 -21
- package/dist/esm/mds-details.entry.js +8 -18
- package/dist/esm/mds-dropdown.entry.js +184 -58
- package/dist/esm/mds-emoji.entry.js +301 -181
- package/dist/esm/mds-entity.entry.js +11 -23
- package/dist/esm/mds-file-preview.entry.js +8 -36
- package/dist/esm/mds-file.entry.js +6 -34
- package/dist/esm/mds-filter-item.entry.js +6 -25
- package/dist/esm/mds-filter.entry.js +19 -32
- package/dist/esm/mds-header-bar.entry.js +11 -27
- package/dist/esm/mds-header.entry.js +8 -22
- package/dist/esm/mds-horizontal-scroll.entry.js +2 -2
- package/dist/esm/mds-hr.entry.js +4 -17
- package/dist/esm/mds-img.entry.js +8 -16
- package/dist/esm/mds-input-date-range-preselection.entry.js +2 -2
- package/dist/esm/mds-input-date-range.entry.js +57 -43
- package/dist/esm/mds-input-date.entry.js +14 -44
- package/dist/esm/mds-input-field.entry.js +42 -6
- package/dist/esm/mds-input-otp.entry.js +37 -3
- package/dist/esm/mds-input-range.entry.js +9 -29
- package/dist/esm/mds-input-select.entry.js +11 -41
- package/dist/esm/mds-input-switch_2.entry.js +19 -55
- package/dist/esm/mds-input-tip_2.entry.js +8 -40
- package/dist/esm/mds-input-upload.entry.js +34 -36
- package/dist/esm/mds-input.entry.js +23 -52
- package/dist/esm/mds-keyboard-key.entry.js +5 -14
- package/dist/esm/mds-keyboard.entry.js +5 -25
- package/dist/esm/mds-kpi-item.entry.js +12 -25
- package/dist/esm/mds-kpi.entry.js +2 -2
- package/dist/esm/mds-label.entry.js +7 -29
- package/dist/esm/mds-list-item.entry.js +4 -13
- package/dist/esm/mds-list.entry.js +1 -1
- package/dist/esm/mds-mention.entry.js +38 -4
- package/dist/esm/mds-modal.entry.js +54 -47
- package/dist/esm/mds-note.entry.js +7 -35
- package/dist/esm/mds-notification.entry.js +12 -14
- package/dist/esm/mds-paginator-item.entry.js +5 -20
- package/dist/esm/mds-paginator.entry.js +27 -32
- package/dist/esm/mds-policy-ai.entry.js +5 -15
- package/dist/esm/mds-pref-animation.entry.js +7 -23
- package/dist/esm/mds-pref-consumption.entry.js +7 -23
- package/dist/esm/mds-pref-contrast.entry.js +10 -24
- package/dist/esm/mds-pref-language-item.entry.js +27 -15
- package/dist/esm/mds-pref-language.entry.js +38 -28
- package/dist/esm/mds-pref-mode.entry.js +271 -0
- package/dist/esm/mds-pref-theme-item.entry.js +41 -0
- package/dist/esm/mds-pref-theme.entry.js +147 -230
- package/dist/esm/mds-pref.entry.js +40 -17
- package/dist/esm/mds-price-table-features-cell.entry.js +4 -25
- package/dist/esm/mds-price-table-features-row.entry.js +4 -25
- package/dist/esm/mds-price-table-features.entry.js +4 -25
- package/dist/esm/mds-price-table-header.entry.js +2 -2
- package/dist/esm/mds-price-table-list-item.entry.js +3 -3
- package/dist/esm/mds-price-table-list.entry.js +4 -25
- package/dist/esm/mds-price-table.entry.js +2 -2
- package/dist/esm/mds-progress_2.entry.js +7 -33
- package/dist/esm/mds-push-notification-item.entry.js +16 -39
- package/dist/esm/mds-push-notification.entry.js +7 -20
- package/dist/esm/mds-quote.entry.js +4 -13
- package/dist/esm/mds-radial-menu-item.entry.js +3 -3
- package/dist/esm/mds-radial-menu.entry.js +7 -6
- package/dist/esm/mds-separator.entry.js +4 -21
- package/dist/esm/mds-status-bar.entry.js +4 -25
- package/dist/esm/mds-stepper-bar-item.entry.js +14 -25
- package/dist/esm/mds-stepper-bar.entry.js +21 -12
- package/dist/esm/mds-tab-bar-item.entry.js +6 -27
- package/dist/esm/mds-tab-bar.entry.js +5 -26
- package/dist/esm/mds-tab_2.entry.js +14 -47
- package/dist/esm/mds-table-body.entry.js +4 -13
- package/dist/esm/mds-table-footer.entry.js +4 -13
- package/dist/esm/mds-table-header-cell.entry.js +4 -13
- package/dist/esm/mds-table-header.entry.js +19 -31
- package/dist/esm/mds-table-row.entry.js +20 -29
- package/dist/esm/mds-table.entry.js +60 -50
- package/dist/esm/mds-text.entry.js +36 -21
- package/dist/esm/mds-toast.entry.js +10 -27
- package/dist/esm/mds-tooltip.entry.js +16 -27
- package/dist/esm/mds-tree-item.entry.js +12 -14
- package/dist/esm/mds-tree.entry.js +12 -6
- package/dist/esm/mds-url-view.entry.js +21 -41
- package/dist/esm/mds-usage.entry.js +5 -33
- package/dist/esm/mds-video-wall.entry.js +8 -4
- package/dist/esm/mds-zero.entry.js +4 -25
- package/dist/esm/preference-CKerJx2M.js +385 -0
- package/dist/esm/slot-C0o_l0td.js +61 -0
- package/dist/esm-es5/date-CACEYk42.js +6 -0
- package/dist/esm-es5/datetime-BJtA1qmE.js +2732 -1
- package/dist/esm-es5/floating-controller-DVldZ5mh.js +66 -0
- package/dist/esm-es5/floating-ui.dom-CHAGzQT-.js +201 -0
- package/dist/esm-es5/form-A9TZf0Ii.js +8 -0
- package/dist/esm-es5/index-DIiEV39g.js +371 -0
- package/dist/esm-es5/index.js +79 -1
- package/dist/esm-es5/keyboard-manager-KRu9I7dw.js +5 -0
- package/dist/esm-es5/loader.js +1 -1
- package/dist/esm-es5/locale-CbJbTW_c.js +230 -0
- package/dist/esm-es5/magma-components.js +4 -1
- package/dist/esm-es5/mds-accordion-item.entry.js +4 -1
- package/dist/esm-es5/mds-accordion-timer-item.entry.js +17 -1
- package/dist/esm-es5/mds-accordion-timer.entry.js +4 -1
- package/dist/esm-es5/mds-accordion.entry.js +7 -1
- package/dist/esm-es5/mds-author.entry.js +1 -1
- package/dist/esm-es5/mds-avatar-stack-item.entry.js +4 -1
- package/dist/esm-es5/mds-avatar-stack.entry.js +1 -1
- package/dist/esm-es5/mds-avatar.entry.js +8 -1
- package/dist/esm-es5/mds-badge.entry.js +12 -1
- package/dist/esm-es5/mds-banner_3.entry.js +40 -1
- package/dist/esm-es5/mds-benchmark-bar.entry.js +15 -1
- package/dist/esm-es5/mds-bibliography.entry.js +14 -1
- package/dist/esm-es5/mds-breadcrumb-item.entry.js +1 -1
- package/dist/esm-es5/mds-breadcrumb.entry.js +4 -1
- package/dist/esm-es5/mds-button-dropdown.entry.js +19 -1
- package/dist/esm-es5/mds-button-group.entry.js +1 -1
- package/dist/esm-es5/mds-button_3.entry.js +42 -1
- package/dist/esm-es5/mds-calendar_2.entry.js +81 -1
- package/dist/esm-es5/mds-card-content.entry.js +1 -1
- package/dist/esm-es5/mds-card-footer.entry.js +1 -1
- package/dist/esm-es5/mds-card-header.entry.js +1 -1
- package/dist/esm-es5/mds-card-media.entry.js +1 -1
- package/dist/esm-es5/mds-card.entry.js +7 -1
- package/dist/esm-es5/mds-details.entry.js +4 -1
- package/dist/esm-es5/mds-dropdown.entry.js +102 -1
- package/dist/esm-es5/mds-emoji.entry.js +899 -3
- package/dist/esm-es5/mds-entity.entry.js +1 -1
- package/dist/esm-es5/mds-file-preview.entry.js +23 -2
- package/dist/esm-es5/mds-file.entry.js +2823 -3
- package/dist/esm-es5/mds-filter-item.entry.js +1 -1
- package/dist/esm-es5/mds-filter.entry.js +11 -1
- package/dist/esm-es5/mds-header-bar.entry.js +11 -1
- package/dist/esm-es5/mds-header.entry.js +30 -1
- package/dist/esm-es5/mds-horizontal-scroll.entry.js +45 -1
- package/dist/esm-es5/mds-hr.entry.js +1 -1
- package/dist/esm-es5/mds-img.entry.js +15 -1
- package/dist/esm-es5/mds-input-date-range-preselection.entry.js +1 -1
- package/dist/esm-es5/mds-input-date-range.entry.js +39 -1
- package/dist/esm-es5/mds-input-date.entry.js +50 -1
- package/dist/esm-es5/mds-input-field.entry.js +22 -1
- package/dist/esm-es5/mds-input-otp.entry.js +13 -1
- package/dist/esm-es5/mds-input-range.entry.js +24 -1
- package/dist/esm-es5/mds-input-select.entry.js +39 -1
- package/dist/esm-es5/mds-input-switch_2.entry.js +27 -1
- package/dist/esm-es5/mds-input-tip_2.entry.js +10 -1
- package/dist/esm-es5/mds-input-upload.entry.js +63 -1
- package/dist/esm-es5/mds-input.entry.js +134 -1
- package/dist/esm-es5/mds-keyboard-key.entry.js +1 -1
- package/dist/esm-es5/mds-keyboard.entry.js +11 -1
- package/dist/esm-es5/mds-kpi-item.entry.js +11 -1
- package/dist/esm-es5/mds-kpi.entry.js +1 -1
- package/dist/esm-es5/mds-label.entry.js +16 -1
- package/dist/esm-es5/mds-list-item.entry.js +7 -1
- package/dist/esm-es5/mds-list.entry.js +1 -1
- package/dist/esm-es5/mds-mention.entry.js +4 -1
- package/dist/esm-es5/mds-modal.entry.js +68 -1
- package/dist/esm-es5/mds-note.entry.js +7 -1
- package/dist/esm-es5/mds-notification.entry.js +13 -1
- package/dist/esm-es5/mds-paginator-item.entry.js +1 -1
- package/dist/esm-es5/mds-paginator.entry.js +14 -1
- package/dist/esm-es5/mds-policy-ai.entry.js +7 -1
- package/dist/esm-es5/mds-pref-animation.entry.js +1 -1
- package/dist/esm-es5/mds-pref-consumption.entry.js +1 -1
- package/dist/esm-es5/mds-pref-contrast.entry.js +4 -1
- package/dist/esm-es5/mds-pref-language-item.entry.js +13 -1
- package/dist/esm-es5/mds-pref-language.entry.js +15 -1
- package/dist/esm-es5/mds-pref-mode.entry.js +4 -0
- package/dist/esm-es5/mds-pref-theme-item.entry.js +13 -0
- package/dist/esm-es5/mds-pref-theme.entry.js +38 -1
- package/dist/esm-es5/mds-pref.entry.js +9 -1
- package/dist/esm-es5/mds-price-table-features-cell.entry.js +4 -1
- package/dist/esm-es5/mds-price-table-features-row.entry.js +1 -1
- package/dist/esm-es5/mds-price-table-features.entry.js +1 -1
- package/dist/esm-es5/mds-price-table-header.entry.js +1 -1
- package/dist/esm-es5/mds-price-table-list-item.entry.js +7 -1
- package/dist/esm-es5/mds-price-table-list.entry.js +1 -1
- package/dist/esm-es5/mds-price-table.entry.js +1 -1
- package/dist/esm-es5/mds-progress_2.entry.js +32 -1
- package/dist/esm-es5/mds-push-notification-item.entry.js +16 -1
- package/dist/esm-es5/mds-push-notification.entry.js +49 -1
- package/dist/esm-es5/mds-quote.entry.js +7 -1
- package/dist/esm-es5/mds-radial-menu-item.entry.js +10 -1
- package/dist/esm-es5/mds-radial-menu.entry.js +28 -1
- package/dist/esm-es5/mds-separator.entry.js +1 -1
- package/dist/esm-es5/mds-status-bar.entry.js +10 -1
- package/dist/esm-es5/mds-stepper-bar-item.entry.js +16 -1
- package/dist/esm-es5/mds-stepper-bar.entry.js +19 -1
- package/dist/esm-es5/mds-tab-bar-item.entry.js +9 -1
- package/dist/esm-es5/mds-tab-bar.entry.js +1 -1
- package/dist/esm-es5/mds-tab_2.entry.js +26 -1
- package/dist/esm-es5/mds-table-body.entry.js +1 -1
- package/dist/esm-es5/mds-table-footer.entry.js +1 -1
- package/dist/esm-es5/mds-table-header-cell.entry.js +4 -1
- package/dist/esm-es5/mds-table-header.entry.js +14 -1
- package/dist/esm-es5/mds-table-row.entry.js +8 -1
- package/dist/esm-es5/mds-table.entry.js +15 -1
- package/dist/esm-es5/mds-text.entry.js +27 -1
- package/dist/esm-es5/mds-toast.entry.js +15 -1
- package/dist/esm-es5/mds-tooltip.entry.js +37 -1
- package/dist/esm-es5/mds-tree-item.entry.js +16 -1
- package/dist/esm-es5/mds-tree.entry.js +20 -1
- package/dist/esm-es5/mds-url-view.entry.js +7 -1
- package/dist/esm-es5/mds-usage.entry.js +4 -1
- package/dist/esm-es5/mds-video-wall.entry.js +16 -1
- package/dist/esm-es5/mds-zero.entry.js +1 -1
- package/dist/esm-es5/preference-CKerJx2M.js +58 -0
- package/dist/esm-es5/slot-C0o_l0td.js +23 -0
- package/dist/hydrate/index.js +4268 -3165
- package/dist/hydrate/index.mjs +4268 -3165
- package/dist/magma-components/index.esm.js +1 -1
- package/dist/magma-components/magma-components.esm.js +1 -1
- package/dist/magma-components/magma-components.js +1 -1
- package/dist/magma-components/p-03be5c0c.entry.js +1 -0
- package/dist/magma-components/p-0715a2cb.system.entry.js +12 -0
- package/dist/magma-components/p-071f18c6.system.entry.js +27 -0
- package/dist/magma-components/p-0798b0bf.system.entry.js +24 -0
- package/dist/magma-components/p-07fde74d.system.entry.js +39 -0
- package/dist/magma-components/p-086fb3aa.entry.js +1 -0
- package/dist/magma-components/p-0a088e7d.system.entry.js +10 -0
- package/dist/magma-components/p-0a691082.entry.js +1 -0
- package/dist/magma-components/p-0ad3b4da.system.entry.js +102 -0
- package/dist/magma-components/p-0af8d821.entry.js +1 -0
- package/dist/magma-components/p-0ec21574.system.entry.js +10 -0
- package/dist/magma-components/p-0f6bb54d.system.entry.js +22 -0
- package/dist/magma-components/p-102d3bd3.system.entry.js +1 -0
- package/dist/magma-components/p-10704ede.system.entry.js +4 -0
- package/dist/magma-components/p-15f63bf3.entry.js +1 -0
- package/dist/magma-components/p-16e9fb14.system.entry.js +7 -0
- package/dist/magma-components/p-1780b8ba.entry.js +1 -0
- package/dist/magma-components/p-181dfb04.entry.js +1 -0
- package/dist/magma-components/p-184720be.system.entry.js +1 -0
- package/dist/magma-components/p-18f7b970.system.entry.js +4 -0
- package/dist/magma-components/p-1a8c5086.system.entry.js +19 -0
- package/dist/magma-components/p-1afc0452.entry.js +1 -0
- package/dist/magma-components/p-1c0a7e24.system.entry.js +30 -0
- package/dist/magma-components/p-1cce738a.system.entry.js +32 -0
- package/dist/magma-components/p-1dcfb13e.entry.js +1 -0
- package/dist/magma-components/p-1df6ac96.system.entry.js +7 -0
- package/dist/magma-components/p-209063b6.system.entry.js +50 -0
- package/dist/magma-components/p-216f95cc.system.entry.js +1 -0
- package/dist/magma-components/p-21891a24.entry.js +1 -0
- package/dist/magma-components/p-21d6687a.system.entry.js +7 -0
- package/dist/magma-components/p-231505e8.entry.js +1 -0
- package/dist/magma-components/p-23e61db9.system.entry.js +4 -0
- package/dist/magma-components/p-241dbf61.entry.js +1 -0
- package/dist/magma-components/p-25935d33.system.entry.js +1 -0
- package/dist/magma-components/p-284c40cd.system.entry.js +4 -0
- package/dist/magma-components/p-29684655.system.entry.js +16 -0
- package/dist/magma-components/p-2b73fee6.entry.js +1 -0
- package/dist/magma-components/p-2d5aadba.system.entry.js +7 -0
- package/dist/magma-components/p-2de17848.entry.js +1 -0
- package/dist/magma-components/p-34482514.entry.js +1 -0
- package/dist/magma-components/p-34c0890e.entry.js +1 -0
- package/dist/magma-components/p-3635eca6.system.entry.js +1 -0
- package/dist/magma-components/p-3b0c1202.entry.js +1 -0
- package/dist/magma-components/p-3d8e63a2.system.entry.js +63 -0
- package/dist/magma-components/p-3db23b5f.system.entry.js +16 -0
- package/dist/magma-components/p-3ec7d3ea.entry.js +1 -0
- package/dist/magma-components/p-3f7d3060.system.entry.js +42 -0
- package/dist/magma-components/p-40563e33.entry.js +1 -0
- package/dist/magma-components/p-41bf6f25.system.entry.js +81 -0
- package/dist/magma-components/p-421a630e.entry.js +1 -0
- package/dist/magma-components/p-4297da23.system.entry.js +1 -0
- package/dist/magma-components/p-4299b76b.system.entry.js +4 -0
- package/dist/magma-components/p-4543501c.entry.js +1 -0
- package/dist/magma-components/p-454c4774.entry.js +1 -0
- package/dist/magma-components/p-4616bc07.entry.js +1 -0
- package/dist/magma-components/p-46786d71.system.entry.js +14 -0
- package/dist/magma-components/p-470e5ac8.system.entry.js +1 -0
- package/dist/magma-components/p-481008e9.system.entry.js +13 -0
- package/dist/magma-components/p-48d37230.entry.js +1 -0
- package/dist/magma-components/p-4b3a8132.system.entry.js +13 -0
- package/dist/magma-components/p-4c8316a8.entry.js +1 -0
- package/dist/magma-components/p-4c95442e.entry.js +1 -0
- package/dist/magma-components/p-4e4bdbf8.entry.js +1 -0
- package/dist/magma-components/p-4e5ab0e4.system.entry.js +16 -0
- package/dist/magma-components/p-54b995c2.system.entry.js +4 -0
- package/dist/magma-components/p-56ad5bf2.entry.js +1 -0
- package/dist/magma-components/p-59de81ac.entry.js +1 -0
- package/dist/magma-components/p-5a7ead55.system.entry.js +37 -0
- package/dist/magma-components/p-5e43274a.system.entry.js +15 -0
- package/dist/magma-components/p-5f545f85.system.entry.js +1 -0
- package/dist/magma-components/p-61a5ac3d.system.entry.js +17 -0
- package/dist/magma-components/p-636cc471.entry.js +1 -0
- package/dist/magma-components/p-66ce2dee.entry.js +1 -0
- package/dist/magma-components/p-67d80d37.system.entry.js +1 -0
- package/dist/magma-components/p-6937f340.entry.js +1 -0
- package/dist/magma-components/p-69d1b815.entry.js +1 -0
- package/dist/magma-components/p-6b7e449f.entry.js +1 -0
- package/dist/magma-components/p-6c417ea1.system.entry.js +913 -0
- package/dist/magma-components/p-6cd7cfe3.entry.js +1 -0
- package/dist/magma-components/p-6ce60d59.entry.js +1 -0
- package/dist/magma-components/p-6cf760ea.system.entry.js +45 -0
- package/dist/magma-components/p-6dc27543.entry.js +1 -0
- package/dist/magma-components/p-6de37588.entry.js +1 -0
- package/dist/magma-components/p-6edc4f16.system.entry.js +14 -0
- package/dist/magma-components/p-6f6b5eb5.entry.js +1 -0
- package/dist/magma-components/p-7090184f.entry.js +1 -0
- package/dist/magma-components/p-716ad14c.entry.js +1 -0
- package/dist/magma-components/p-71804224.entry.js +1 -0
- package/dist/magma-components/p-735dc594.system.entry.js +1 -0
- package/dist/magma-components/p-739fdf76.system.entry.js +1 -0
- package/dist/magma-components/p-74b0902a.entry.js +1 -0
- package/dist/magma-components/p-7530a2f2.entry.js +1 -0
- package/dist/magma-components/p-75dd012a.system.entry.js +11 -0
- package/dist/magma-components/p-75fcf1a4.entry.js +1 -0
- package/dist/magma-components/p-76ae22d6.entry.js +1 -0
- package/dist/magma-components/p-78248693.entry.js +1 -0
- package/dist/magma-components/p-78fef00a.entry.js +1 -0
- package/dist/magma-components/p-7c0d202c.entry.js +1 -0
- package/dist/magma-components/p-7d317ff0.entry.js +8 -0
- package/dist/magma-components/p-7f2e3b74.system.entry.js +2838 -0
- package/dist/magma-components/p-7fc29447.entry.js +1 -0
- package/dist/magma-components/p-8103d4d4.system.entry.js +30 -0
- package/dist/magma-components/p-81b72b6e.entry.js +1 -0
- package/dist/magma-components/p-859ab5a2.entry.js +18 -0
- package/dist/magma-components/p-896ae0ee.entry.js +1 -0
- package/dist/magma-components/p-89a3bc7a.system.entry.js +16 -0
- package/dist/magma-components/p-8b7fa8d7.entry.js +1 -0
- package/dist/magma-components/p-8dff6606.system.entry.js +11 -0
- package/dist/magma-components/p-8e40eda3.system.entry.js +9 -0
- package/dist/magma-components/p-91b9d4e7.system.entry.js +4 -0
- package/dist/magma-components/p-92e1001f.entry.js +1 -0
- package/dist/magma-components/p-9378b373.system.entry.js +49 -0
- package/dist/magma-components/p-960dc9b5.system.entry.js +15 -0
- package/dist/magma-components/p-9626eaff.system.entry.js +134 -0
- package/dist/magma-components/p-9741d95e.system.entry.js +7 -0
- package/dist/magma-components/p-97ea9e6e.system.entry.js +68 -0
- package/dist/magma-components/p-9846fe89.system.entry.js +1 -0
- package/dist/magma-components/p-998721b9.system.entry.js +1 -0
- package/dist/magma-components/p-9a5296c0.system.entry.js +7 -0
- package/dist/magma-components/p-9b2ee3fe.entry.js +1 -0
- package/dist/magma-components/p-9be4a736.entry.js +1 -0
- package/dist/magma-components/p-9ca7932d.system.entry.js +8 -0
- package/dist/magma-components/p-9d86477d.system.entry.js +1 -0
- package/dist/magma-components/p-9d9a947b.entry.js +18 -0
- package/dist/magma-components/p-9e3bc553.system.entry.js +26 -0
- package/dist/magma-components/p-9e58467e.system.entry.js +10 -0
- package/dist/magma-components/p-9e9a1ebd.system.entry.js +15 -0
- package/dist/magma-components/p-A9TZf0Ii.js +1 -0
- package/dist/magma-components/p-BFnx_0hM.js +5 -0
- package/dist/magma-components/p-BJKToXNf.system.js +2733 -1
- package/dist/magma-components/p-BbMKuVem.js +1 -0
- package/dist/magma-components/p-C0o_l0td.js +1 -0
- package/dist/magma-components/p-C2FHijr2.system.js +231 -0
- package/dist/magma-components/p-CACEYk42.js +1 -0
- package/dist/magma-components/p-CBam2PI8.system.js +79 -0
- package/dist/magma-components/p-CDTiTqY0.system.js +58 -0
- package/dist/magma-components/p-CHAGzQT-.js +1 -0
- package/dist/magma-components/p-CI85vVs8.system.js +9 -0
- package/dist/magma-components/p-CnXBPjmc.system.js +5 -0
- package/dist/magma-components/p-DB8Rm54c.js +1 -0
- package/dist/magma-components/p-DIiEV39g.js +3 -0
- package/dist/magma-components/p-Dg8nxRUX.system.js +201 -0
- package/dist/magma-components/p-DmC-b-ZK.system.js +67 -0
- package/dist/magma-components/p-KRu9I7dw.js +1 -0
- package/dist/magma-components/p-LerCJgfP.system.js +5 -0
- package/dist/magma-components/p-MGv0i39Y.system.js +162 -0
- package/dist/magma-components/p-RJ5ZA1kY.system.js +23 -0
- package/dist/magma-components/p-a3279a73.system.entry.js +11 -0
- package/dist/magma-components/p-a3b0f586.entry.js +1 -0
- package/dist/magma-components/p-a3fc2ea4.system.entry.js +39 -0
- package/dist/magma-components/p-a5ac5e0b.entry.js +1 -0
- package/dist/magma-components/p-a8ec3080.system.entry.js +27 -0
- package/dist/magma-components/p-a906a02f.system.entry.js +16 -0
- package/dist/magma-components/p-a93b2a39.entry.js +1 -0
- package/dist/magma-components/p-aa267e7b.entry.js +1 -0
- package/dist/magma-components/p-ab9095ae.system.entry.js +4 -0
- package/dist/magma-components/p-ac544ab1.entry.js +1 -0
- package/dist/magma-components/p-ace198e9.entry.js +1 -0
- package/dist/magma-components/p-ad3983b2.entry.js +1 -0
- package/dist/magma-components/p-af41c8b8.system.entry.js +1 -0
- package/dist/magma-components/p-af45f0a5.system.entry.js +20 -0
- package/dist/magma-components/p-b23a6c83.entry.js +1 -0
- package/dist/magma-components/p-b3a3578c.entry.js +1 -0
- package/dist/magma-components/p-b49e0321.system.entry.js +1 -0
- package/dist/magma-components/p-b71e0d51.entry.js +1 -0
- package/dist/magma-components/p-b8d4a14e.entry.js +1 -0
- package/dist/magma-components/p-b9fecfd5.entry.js +1 -0
- package/dist/magma-components/p-ba035f90.entry.js +1 -0
- package/dist/magma-components/p-bc51d310.system.entry.js +1 -0
- package/dist/magma-components/p-bd490a8e.entry.js +1 -0
- package/dist/magma-components/p-be198039.system.entry.js +4 -0
- package/dist/magma-components/p-be692266.system.entry.js +13 -0
- package/dist/magma-components/p-bf7168b4.entry.js +1 -0
- package/dist/magma-components/p-bf84d9fa.entry.js +1 -0
- package/dist/magma-components/p-c1fb2eb7.entry.js +1 -0
- package/dist/magma-components/p-c4e58240.entry.js +1 -0
- package/dist/magma-components/p-c573de10.entry.js +1 -0
- package/dist/magma-components/p-c6be3db7.system.entry.js +1 -0
- package/dist/magma-components/p-c70d7159.entry.js +1 -0
- package/dist/magma-components/p-c7517884.system.entry.js +38 -0
- package/dist/magma-components/p-c9be79bd.entry.js +1 -0
- package/dist/magma-components/p-c9e12c2b.system.entry.js +7 -0
- package/dist/magma-components/p-cb6a1908.entry.js +1 -0
- package/dist/magma-components/p-cbd5aef4.system.entry.js +14 -0
- package/dist/magma-components/p-cd21137b.system.entry.js +1 -0
- package/dist/magma-components/p-cd5866c8.entry.js +1 -0
- package/dist/magma-components/p-ce0ecc75.system.entry.js +15 -0
- package/dist/magma-components/p-ce4e1a41.system.entry.js +1 -0
- package/dist/magma-components/p-d3116844.entry.js +1 -0
- package/dist/magma-components/p-d38165ed.system.entry.js +1 -0
- package/dist/magma-components/p-d3933a22.entry.js +1 -0
- package/dist/magma-components/p-d44c49d6.system.entry.js +8 -0
- package/dist/magma-components/p-d4a529ce.entry.js +1 -0
- package/dist/magma-components/p-d6d4aa1a.entry.js +1 -0
- package/dist/magma-components/p-d81e7100.system.entry.js +15 -0
- package/dist/magma-components/p-d8c27f4b.entry.js +1 -0
- package/dist/magma-components/p-d921d876.entry.js +1 -0
- package/dist/magma-components/p-da1ac3e1.entry.js +1 -0
- package/dist/magma-components/p-ddbdce09.entry.js +1 -0
- package/dist/magma-components/p-de6bc3c8.entry.js +1 -0
- package/dist/magma-components/p-df2b7607.system.entry.js +4 -0
- package/dist/magma-components/p-e05d2df8.system.entry.js +4 -0
- package/dist/magma-components/p-e0b2ef8f.system.entry.js +1 -0
- package/dist/magma-components/p-e0c50a2d.entry.js +1 -0
- package/dist/magma-components/p-e1277efe.system.entry.js +1 -0
- package/dist/magma-components/p-e1e6dd97.entry.js +1 -0
- package/dist/magma-components/p-e2f7a9bd.system.entry.js +1 -0
- package/dist/magma-components/p-e3e893c4.entry.js +1 -0
- package/dist/magma-components/p-e4868ade.entry.js +1 -0
- package/dist/magma-components/p-e5c6f9a9.system.entry.js +7 -0
- package/dist/magma-components/p-e5da7036.entry.js +1 -0
- package/dist/magma-components/p-e6dccab5.system.entry.js +1 -0
- package/dist/magma-components/p-ec59ec9a.entry.js +1 -0
- package/dist/magma-components/p-eddcef53.system.entry.js +1 -0
- package/dist/magma-components/p-eed00e7f.system.entry.js +1 -0
- package/dist/magma-components/p-ef8cb401.entry.js +1 -0
- package/dist/magma-components/p-efe8d359.entry.js +1 -0
- package/dist/magma-components/p-f070a5b5.system.entry.js +11 -0
- package/dist/magma-components/p-f0a168f4.system.entry.js +13 -0
- package/dist/magma-components/p-f1462410.system.entry.js +9 -0
- package/dist/magma-components/p-f23d4974.entry.js +1 -0
- package/dist/magma-components/p-f542246f.system.entry.js +1 -0
- package/dist/magma-components/p-f5c680dd.entry.js +1 -0
- package/dist/magma-components/p-f60c6e8e.system.entry.js +40 -0
- package/dist/magma-components/p-f8369939.entry.js +1 -0
- package/dist/magma-components/p-f97ede3e.system.entry.js +19 -0
- package/dist/magma-components/p-f97ff5b2.entry.js +1 -0
- package/dist/magma-components/p-fe1662e8.system.entry.js +28 -0
- package/dist/magma-components/p-ff133cbd.entry.js +1 -0
- package/dist/magma-components/p-fff44704.entry.js +1 -0
- package/dist/magma-components/p-opeIIa7t.system.js +7 -0
- package/dist/stats.json +5337 -7124
- package/dist/types/common/date.d.ts +5 -1
- package/dist/types/common/floating-controller.d.ts +56 -2
- package/dist/types/common/form.d.ts +10 -0
- package/dist/types/common/locale.d.ts +0 -5
- package/dist/types/common/preference.d.ts +48 -16
- package/dist/types/common/slot.d.ts +11 -1
- package/dist/types/common/yugop/random-text.d.ts +8 -0
- package/dist/types/components/mds-accordion/mds-accordion.d.ts +0 -8
- package/dist/types/components/mds-accordion-item/mds-accordion-item.d.ts +0 -10
- package/dist/types/components/mds-accordion-timer-item/mds-accordion-timer-item.d.ts +0 -4
- package/dist/types/components/mds-author/mds-author.d.ts +2 -1
- package/dist/types/components/mds-avatar/mds-avatar.d.ts +0 -6
- package/dist/types/components/mds-badge/mds-badge.d.ts +0 -10
- package/dist/types/components/mds-banner/mds-banner.d.ts +2 -16
- package/dist/types/components/mds-breadcrumb/mds-breadcrumb.d.ts +0 -6
- package/dist/types/components/mds-button/mds-button.d.ts +0 -7
- package/dist/types/components/mds-button-group/mds-button-group.d.ts +1 -1
- package/dist/types/components/mds-calendar/mds-calendar.d.ts +27 -18
- package/dist/types/components/mds-card/mds-card.d.ts +0 -8
- package/dist/types/components/mds-card-header/mds-card-header.d.ts +2 -1
- package/dist/types/components/mds-chip/mds-chip.d.ts +0 -15
- package/dist/types/components/mds-details/mds-details.d.ts +0 -5
- package/dist/types/components/mds-dropdown/mds-dropdown.d.ts +33 -12
- package/dist/types/components/mds-emoji/mds-emoji.d.ts +9 -2
- package/dist/types/components/mds-entity/mds-entity.d.ts +3 -10
- package/dist/types/components/mds-file/mds-file.d.ts +0 -15
- package/dist/types/components/mds-file-preview/mds-file-preview.d.ts +0 -15
- package/dist/types/components/mds-filter/mds-filter.d.ts +10 -10
- package/dist/types/components/mds-filter-item/mds-filter-item.d.ts +0 -9
- package/dist/types/components/mds-header/mds-header.d.ts +0 -7
- package/dist/types/components/mds-header-bar/mds-header-bar.d.ts +2 -11
- package/dist/types/components/mds-hr/mds-hr.d.ts +0 -6
- package/dist/types/components/mds-img/mds-img.d.ts +1 -7
- package/dist/types/components/mds-input/mds-input.d.ts +7 -15
- package/dist/types/components/mds-input-date/mds-input-date.d.ts +9 -14
- package/dist/types/components/mds-input-date-range/mds-input-date-range.d.ts +9 -12
- package/dist/types/components/mds-input-field/mds-input-field.d.ts +3 -0
- package/dist/types/components/mds-input-otp/mds-input-otp.d.ts +7 -0
- package/dist/types/components/mds-input-range/mds-input-range.d.ts +0 -10
- package/dist/types/components/mds-input-select/mds-input-select.d.ts +5 -14
- package/dist/types/components/mds-input-switch/mds-input-switch.d.ts +0 -11
- package/dist/types/components/mds-input-tip/mds-input-tip.d.ts +0 -4
- package/dist/types/components/mds-input-tip-item/mds-input-tip-item.d.ts +0 -13
- package/dist/types/components/mds-input-upload/mds-input-upload.d.ts +2 -7
- package/dist/types/components/mds-input-upload/meta/types.d.ts +1 -1
- package/dist/types/components/mds-keyboard/mds-keyboard.d.ts +0 -11
- package/dist/types/components/mds-keyboard-key/mds-keyboard-key.d.ts +0 -7
- package/dist/types/components/mds-keyboard-key/meta/icons.d.ts +1 -1
- package/dist/types/components/mds-kpi-item/mds-kpi-item.d.ts +8 -10
- package/dist/types/components/mds-label/mds-label.d.ts +0 -12
- package/dist/types/components/mds-list-item/mds-list-item.d.ts +0 -4
- package/dist/types/components/mds-mention/mds-mention.d.ts +13 -0
- package/dist/types/components/mds-mention/meta/interface.d.ts +5 -0
- package/dist/types/components/mds-modal/mds-modal.d.ts +17 -16
- package/dist/types/components/mds-note/mds-note.d.ts +0 -15
- package/dist/types/components/mds-notification/mds-notification.d.ts +0 -3
- package/dist/types/components/mds-paginator/mds-paginator.d.ts +9 -11
- package/dist/types/components/mds-paginator-item/mds-paginator-item.d.ts +0 -7
- package/dist/types/components/mds-policy-ai/mds-policy-ai.d.ts +0 -7
- package/dist/types/components/mds-pref/mds-pref.d.ts +12 -8
- package/dist/types/components/mds-pref-animation/mds-pref-animation.d.ts +0 -10
- package/dist/types/components/mds-pref-consumption/mds-pref-consumption.d.ts +0 -10
- package/dist/types/components/mds-pref-contrast/mds-pref-contrast.d.ts +0 -10
- package/dist/types/components/mds-pref-language/mds-pref-language.d.ts +3 -9
- package/dist/types/components/mds-pref-language-item/mds-pref-language-item.d.ts +3 -7
- package/dist/types/components/mds-pref-mode/mds-pref-mode.d.ts +62 -0
- package/dist/types/components/mds-pref-mode/meta/dictionary.d.ts +3 -0
- package/dist/types/components/mds-pref-theme/mds-pref-theme.d.ts +63 -45
- package/dist/types/components/mds-pref-theme/meta/dictionary.d.ts +2 -3
- package/dist/types/components/mds-pref-theme-item/mds-pref-theme-item.d.ts +28 -0
- package/dist/types/components/mds-price-table-features/mds-price-table-features.d.ts +0 -10
- package/dist/types/components/mds-price-table-features-cell/mds-price-table-features-cell.d.ts +0 -10
- package/dist/types/components/mds-price-table-features-row/mds-price-table-features-row.d.ts +0 -10
- package/dist/types/components/mds-price-table-list/mds-price-table-list.d.ts +0 -10
- package/dist/types/components/mds-progress/mds-progress.d.ts +0 -10
- package/dist/types/components/mds-push-notification/mds-push-notification.d.ts +0 -6
- package/dist/types/components/mds-push-notification-item/mds-push-notification-item.d.ts +3 -17
- package/dist/types/components/mds-quote/mds-quote.d.ts +0 -4
- package/dist/types/components/mds-radial-progress/mds-radial-progress.d.ts +0 -1
- package/dist/types/components/mds-separator/mds-separator.d.ts +0 -8
- package/dist/types/components/mds-spinner/mds-spinner.d.ts +0 -4
- package/dist/types/components/mds-status-bar/mds-status-bar.d.ts +0 -10
- package/dist/types/components/mds-stepper-bar/mds-stepper-bar.d.ts +10 -0
- package/dist/types/components/mds-stepper-bar-item/mds-stepper-bar-item.d.ts +0 -9
- package/dist/types/components/mds-tab/mds-tab.d.ts +0 -9
- package/dist/types/components/mds-tab-bar/mds-tab-bar.d.ts +0 -10
- package/dist/types/components/mds-tab-bar-item/mds-tab-bar-item.d.ts +0 -10
- package/dist/types/components/mds-tab-item/mds-tab-item.d.ts +5 -8
- package/dist/types/components/mds-table/mds-table.d.ts +10 -14
- package/dist/types/components/mds-table-body/mds-table-body.d.ts +0 -4
- package/dist/types/components/mds-table-cell/mds-table-cell.d.ts +0 -4
- package/dist/types/components/mds-table-footer/mds-table-footer.d.ts +0 -4
- package/dist/types/components/mds-table-header/mds-table-header.d.ts +0 -9
- package/dist/types/components/mds-table-header-cell/mds-table-header-cell.d.ts +0 -4
- package/dist/types/components/mds-table-row/mds-table-row.d.ts +3 -10
- package/dist/types/components/mds-text/mds-text.d.ts +0 -4
- package/dist/types/components/mds-toast/mds-toast.d.ts +2 -11
- package/dist/types/components/mds-tooltip/mds-tooltip.d.ts +0 -9
- package/dist/types/components/mds-tree-item/mds-tree-item.d.ts +1 -5
- package/dist/types/components/mds-url-view/mds-url-view.d.ts +0 -15
- package/dist/types/components/mds-usage/mds-usage.d.ts +0 -16
- package/dist/types/components/mds-video-wall/mds-video-wall.d.ts +2 -1
- package/dist/types/components/mds-zero/mds-zero.d.ts +0 -10
- package/dist/types/components.d.ts +243 -239
- package/dist/types/event-detail/preference.d.ts +2 -2
- package/dist/types/event-detail/theme.d.ts +5 -0
- package/dist/types/stencil-public-runtime.d.ts +12 -0
- package/dist/types/type/preference.d.ts +16 -3
- package/loader/index.d.ts +1 -1
- package/package.json +58 -64
- package/dist/cjs/date-dnDGaLCn.js +0 -16
- package/dist/cjs/floating-controller-CXEVR1wX.js +0 -203
- package/dist/cjs/floating-ui.dom-DW-02Mib.js +0 -1703
- package/dist/cjs/index-CNuKb6Lv.js +0 -2896
- package/dist/cjs/keyboard-manager-BXKT5TGW.js +0 -52
- package/dist/cjs/locale-oGW3SvGJ.js +0 -837
- package/dist/cjs/mds-pref-theme-variant-item.cjs.entry.js +0 -63
- package/dist/cjs/mds-pref-theme-variant.cjs.entry.js +0 -149
- package/dist/cjs/preference-BdpIXWLP.js +0 -81
- package/dist/cjs/slot-CI0KpgtY.js +0 -52
- package/dist/collection/components/mds-accordion/test/mds-accordion.stories.js +0 -39
- package/dist/collection/components/mds-accordion-item/test/mds-accordion-item.stories.js +0 -35
- package/dist/collection/components/mds-accordion-timer/test/mds-accordion-timer.stories.js +0 -51
- package/dist/collection/components/mds-accordion-timer-item/test/mds-accordion-timer-item.stories.js +0 -52
- package/dist/collection/components/mds-author/test/mds-author.stories.js +0 -12
- package/dist/collection/components/mds-avatar/test/mds-avatar.stories.js +0 -71
- package/dist/collection/components/mds-avatar-stack/test/mds-avatar-stack.stories.js +0 -34
- package/dist/collection/components/mds-avatar-stack-item/test/mds-avatar-stack-item.stories.js +0 -60
- package/dist/collection/components/mds-badge/test/mds-badge.stories.js +0 -46
- package/dist/collection/components/mds-banner/test/mds-banner.stories.js +0 -106
- package/dist/collection/components/mds-benchmark-bar/test/mds-benchmark-bar.stories.js +0 -64
- package/dist/collection/components/mds-bibliography/test/mds-bibliography.stories.js +0 -104
- package/dist/collection/components/mds-breadcrumb/test/mds-breadcrumb.stories.js +0 -14
- package/dist/collection/components/mds-breadcrumb-item/test/mds-breadcrumb-item.stories.js +0 -24
- package/dist/collection/components/mds-button/test/mds-button.stories.js +0 -346
- package/dist/collection/components/mds-button-dropdown/test/mds-button-dropdown.stories.js +0 -73
- package/dist/collection/components/mds-button-group/test/mds-button-group.stories.js +0 -12
- package/dist/collection/components/mds-calendar/test/mds-calendar.stories.js +0 -24
- package/dist/collection/components/mds-card/test/mds-card.stories.js +0 -82
- package/dist/collection/components/mds-chip/test/mds-chip.stories.js +0 -120
- package/dist/collection/components/mds-details/test/mds-details.stories.js +0 -20
- package/dist/collection/components/mds-dropdown/test/mds-dropdown.stories.js +0 -256
- package/dist/collection/components/mds-emoji/test/mds-emoji.stories.js +0 -87
- package/dist/collection/components/mds-entity/test/mds-entity.stories.js +0 -101
- package/dist/collection/components/mds-file/test/mds-file.stories.js +0 -73
- package/dist/collection/components/mds-file-preview/test/mds-file-preview.stories.js +0 -154
- package/dist/collection/components/mds-filter/test/mds-filter.stories.js +0 -49
- package/dist/collection/components/mds-filter-item/test/mds-filter-item.stories.js +0 -36
- package/dist/collection/components/mds-header/test/mds-header.stories.js +0 -71
- package/dist/collection/components/mds-header-bar/test/mds-header-bar.stories.js +0 -21
- package/dist/collection/components/mds-help/test/mds-help.stories.js +0 -23
- package/dist/collection/components/mds-horizontal-scroll/test/mds-horizontal-scroll.stories.js +0 -48
- package/dist/collection/components/mds-hr/test/mds-hr.stories.js +0 -14
- package/dist/collection/components/mds-icon/test/mds-icon.stories.js +0 -76
- package/dist/collection/components/mds-img/test/mds-img-accessibility.stories.js +0 -34
- package/dist/collection/components/mds-img/test/mds-img.stories.js +0 -62
- package/dist/collection/components/mds-input/test/mds-input.stories.js +0 -302
- package/dist/collection/components/mds-input-date/test/mds-input-date.stories.js +0 -70
- package/dist/collection/components/mds-input-date-range/test/mds-input-date-range.stories.js +0 -109
- package/dist/collection/components/mds-input-field/test/mds-input-field.stories.js +0 -90
- package/dist/collection/components/mds-input-otp/test/mds-input-otp.stories.js +0 -68
- package/dist/collection/components/mds-input-range/test/mds-input-range.stories.js +0 -92
- package/dist/collection/components/mds-input-select/test/mds-input-select.stories.js +0 -97
- package/dist/collection/components/mds-input-switch/test/mds-input-switch.stories.js +0 -169
- package/dist/collection/components/mds-input-tip/test/mds-input-tip.stories.js +0 -20
- package/dist/collection/components/mds-input-tip-item/test/mds-input-tip.stories.js +0 -20
- package/dist/collection/components/mds-input-upload/test/mds-input-upload.stories.js +0 -48
- package/dist/collection/components/mds-keyboard/test/mds-keyboard.stories.js +0 -30
- package/dist/collection/components/mds-keyboard-key/test/mds-keyboard-key.stories.js +0 -20
- package/dist/collection/components/mds-kpi/test/mds-kpi.stories.js +0 -22
- package/dist/collection/components/mds-kpi-item/test/mds-kpi-item.stories.js +0 -34
- package/dist/collection/components/mds-label/test/mds-label.stories.js +0 -72
- package/dist/collection/components/mds-list/test/mds-list.stories.js +0 -8
- package/dist/collection/components/mds-list-item/test/mds-list-item.stories.js +0 -29
- package/dist/collection/components/mds-mention/test/mds-mention.stories.js +0 -31
- package/dist/collection/components/mds-modal/test/mds-modal.stories.js +0 -388
- package/dist/collection/components/mds-note/test/mds-note.stories.js +0 -31
- package/dist/collection/components/mds-notification/test/mds-notification.stories.js +0 -64
- package/dist/collection/components/mds-paginator/test/mds-paginator.stories.js +0 -28
- package/dist/collection/components/mds-policy-ai/test/mds-policy.stories.js +0 -82
- package/dist/collection/components/mds-pref/test/mds-pref.stories.js +0 -26
- package/dist/collection/components/mds-pref-animation/test/mds-pref-animation.stories.js +0 -18
- package/dist/collection/components/mds-pref-consumption/test/mds-pref-consumption.stories.js +0 -18
- package/dist/collection/components/mds-pref-contrast/test/mds-pref-contrast.stories.js +0 -18
- package/dist/collection/components/mds-pref-language/test/mds-pref-language.stories.js +0 -18
- package/dist/collection/components/mds-pref-theme/test/mds-pref-theme.stories.js +0 -24
- package/dist/collection/components/mds-pref-theme-variant/mds-pref-theme-variant.css +0 -40
- package/dist/collection/components/mds-pref-theme-variant/mds-pref-theme-variant.js +0 -288
- package/dist/collection/components/mds-pref-theme-variant/meta/dictionary.js +0 -2
- package/dist/collection/components/mds-pref-theme-variant/test/mds-pref-theme-variant.stories.js +0 -27
- package/dist/collection/components/mds-pref-theme-variant-item/mds-pref-theme-variant-item.css +0 -100
- package/dist/collection/components/mds-pref-theme-variant-item/mds-pref-theme-variant-item.js +0 -198
- package/dist/collection/components/mds-price-table/test/mds-price-table.stories.js +0 -11
- package/dist/collection/components/mds-price-table-features/test/mds-price-table-features.stories.js +0 -11
- package/dist/collection/components/mds-price-table-features-cell/test/mds-price-table-features-cell.stories.js +0 -11
- package/dist/collection/components/mds-price-table-header/test/mds-price-table-header.stories.js +0 -8
- package/dist/collection/components/mds-price-table-list/test/mds-price-table-list.stories.js +0 -12
- package/dist/collection/components/mds-progress/test/mds-progress.stories.js +0 -66
- package/dist/collection/components/mds-push-notification/test/mds-push-notification.stories.js +0 -104
- package/dist/collection/components/mds-push-notification-item/test/mds-push-notification-item.stories.js +0 -194
- package/dist/collection/components/mds-quote/test/mds-quote.stories.js +0 -33
- package/dist/collection/components/mds-radial-menu/test/mds-radial-menu.stories.js +0 -98
- package/dist/collection/components/mds-radial-menu-item/test/mds-radial-menu-item.stories.js +0 -37
- package/dist/collection/components/mds-radial-progress/test/mds-radial-progress.stories.js +0 -45
- package/dist/collection/components/mds-separator/test/mds-separator.stories.js +0 -8
- package/dist/collection/components/mds-spinner/test/mds-spinner.stories.js +0 -20
- package/dist/collection/components/mds-status-bar/test/mds-status-bar.stories.js +0 -80
- package/dist/collection/components/mds-stepper-bar/test/mds-stepper-bar.stories.js +0 -100
- package/dist/collection/components/mds-stepper-bar-item/test/mds-stepper-bar-item.stories.js +0 -70
- package/dist/collection/components/mds-tab/test/mds-tab.stories.js +0 -152
- package/dist/collection/components/mds-tab-bar/test/mds-tab-bar.stories.js +0 -8
- package/dist/collection/components/mds-tab-bar-item/test/mds-tab-bar-item.stories.js +0 -21
- package/dist/collection/components/mds-tab-item/test/mds-tab-item.stories.js +0 -54
- package/dist/collection/components/mds-table/test/mds-table.stories.js +0 -107
- package/dist/collection/components/mds-text/test/mds-text.stories.js +0 -183
- package/dist/collection/components/mds-toast/test/mds-toast.stories.js +0 -52
- package/dist/collection/components/mds-tooltip/test/mds-tooltip.stories.js +0 -155
- package/dist/collection/components/mds-tree/test/mds-tree-apk.stories.js +0 -66
- package/dist/collection/components/mds-tree/test/mds-tree.stories.js +0 -83
- package/dist/collection/components/mds-tree-item/test/mds-tree-item.stories.js +0 -71
- package/dist/collection/components/mds-url-view/test/mds-url-view.stories.js +0 -75
- package/dist/collection/components/mds-usage/test/mds-usage.stories.js +0 -33
- package/dist/collection/components/mds-video-wall/test/mds-video-wall.stories.js +0 -104
- package/dist/collection/components/mds-zero/test/mds-zero.stories.js +0 -8
- package/dist/collection/storybook/box-shadows.stories.js +0 -53
- package/dist/collection/storybook/color-scale.stories.js +0 -465
- package/dist/collection/storybook/components-preview.stories.js +0 -36
- package/dist/collection/storybook/example-page.stories.js +0 -10
- package/dist/collection/storybook/fouc-hydrated.stories.js +0 -20
- package/dist/collection/storybook/input-form.stories.js +0 -40
- package/dist/collection/storybook/same-childrend-slot-names.stories.js +0 -10
- package/dist/collection/test/file.js +0 -53
- package/dist/collection/test/mock.js +0 -19
- package/dist/components/date.js +0 -1
- package/dist/components/floating-controller.js +0 -1
- package/dist/components/floating-ui.dom.js +0 -1
- package/dist/components/icons-set.service.js +0 -1
- package/dist/components/keyboard-manager.js +0 -1
- package/dist/components/locale.it.js +0 -1
- package/dist/components/locale.js +0 -5
- package/dist/components/mds-avatar-stack-item2.js +0 -1
- package/dist/components/mds-avatar2.js +0 -1
- package/dist/components/mds-badge2.js +0 -1
- package/dist/components/mds-banner2.js +0 -1
- package/dist/components/mds-button2.js +0 -1
- package/dist/components/mds-calendar-cell2.js +0 -1
- package/dist/components/mds-calendar2.js +0 -1
- package/dist/components/mds-chip2.js +0 -1
- package/dist/components/mds-dropdown2.js +0 -1
- package/dist/components/mds-file-preview2.js +0 -8
- package/dist/components/mds-filter-item2.js +0 -1
- package/dist/components/mds-help2.js +0 -1
- package/dist/components/mds-icon2.js +0 -1
- package/dist/components/mds-img2.js +0 -1
- package/dist/components/mds-input-switch2.js +0 -1
- package/dist/components/mds-input-tip-item2.js +0 -1
- package/dist/components/mds-input-tip2.js +0 -1
- package/dist/components/mds-input2.js +0 -1
- package/dist/components/mds-modal2.js +0 -1
- package/dist/components/mds-paginator-item2.js +0 -1
- package/dist/components/mds-pref-theme-variant-item.d.ts +0 -11
- package/dist/components/mds-pref-theme-variant-item.js +0 -1
- package/dist/components/mds-pref-theme-variant.d.ts +0 -11
- package/dist/components/mds-pref-theme-variant.js +0 -1
- package/dist/components/mds-progress2.js +0 -1
- package/dist/components/mds-radial-progress2.js +0 -1
- package/dist/components/mds-separator2.js +0 -1
- package/dist/components/mds-spinner2.js +0 -1
- package/dist/components/mds-tab-item2.js +0 -1
- package/dist/components/mds-tab2.js +0 -1
- package/dist/components/mds-table-cell2.js +0 -1
- package/dist/components/mds-table-header-cell2.js +0 -1
- package/dist/components/mds-text2.js +0 -1
- package/dist/components/mds-tooltip2.js +0 -1
- package/dist/components/preference.js +0 -1
- package/dist/components/slot.js +0 -1
- package/dist/esm/date-C1oxPa_J.js +0 -14
- package/dist/esm/floating-controller-D5eXU5Mk.js +0 -200
- package/dist/esm/floating-ui.dom-8RYXTPXs.js +0 -1695
- package/dist/esm/index-CAd5312P.js +0 -2869
- package/dist/esm/keyboard-manager-BudfaWhu.js +0 -50
- package/dist/esm/locale-a4oAcjYG.js +0 -835
- package/dist/esm/mds-pref-theme-variant-item.entry.js +0 -61
- package/dist/esm/mds-pref-theme-variant.entry.js +0 -147
- package/dist/esm/preference-fMwnXhio.js +0 -79
- package/dist/esm/slot-ttrRC6OE.js +0 -48
- package/dist/esm-es5/date-C1oxPa_J.js +0 -1
- package/dist/esm-es5/floating-controller-D5eXU5Mk.js +0 -1
- package/dist/esm-es5/floating-ui.dom-8RYXTPXs.js +0 -1
- package/dist/esm-es5/index-CAd5312P.js +0 -1
- package/dist/esm-es5/keyboard-manager-BudfaWhu.js +0 -1
- package/dist/esm-es5/locale-a4oAcjYG.js +0 -5
- package/dist/esm-es5/mds-pref-theme-variant-item.entry.js +0 -1
- package/dist/esm-es5/mds-pref-theme-variant.entry.js +0 -1
- package/dist/esm-es5/preference-fMwnXhio.js +0 -1
- package/dist/esm-es5/slot-ttrRC6OE.js +0 -1
- package/dist/magma-components/p-0105d7c7.entry.js +0 -8
- package/dist/magma-components/p-022defe8.entry.js +0 -1
- package/dist/magma-components/p-02d858d0.entry.js +0 -1
- package/dist/magma-components/p-0607a2b3.entry.js +0 -1
- package/dist/magma-components/p-0af4d0ef.entry.js +0 -1
- package/dist/magma-components/p-0b91aae4.entry.js +0 -1
- package/dist/magma-components/p-0bb29dbd.system.entry.js +0 -1
- package/dist/magma-components/p-0c1a5df0.entry.js +0 -1
- package/dist/magma-components/p-0e986d85.entry.js +0 -18
- package/dist/magma-components/p-0ea42813.entry.js +0 -1
- package/dist/magma-components/p-0fe5aeaf.system.entry.js +0 -1
- package/dist/magma-components/p-10ddec99.system.entry.js +0 -1
- package/dist/magma-components/p-11567740.entry.js +0 -1
- package/dist/magma-components/p-116238cf.system.entry.js +0 -1
- package/dist/magma-components/p-1239667c.system.entry.js +0 -1
- package/dist/magma-components/p-1518fda3.system.entry.js +0 -1
- package/dist/magma-components/p-16c94506.system.entry.js +0 -1
- package/dist/magma-components/p-18823bfc.system.entry.js +0 -1
- package/dist/magma-components/p-188e94ef.system.entry.js +0 -1
- package/dist/magma-components/p-19446c9e.entry.js +0 -1
- package/dist/magma-components/p-1a73c7b0.system.entry.js +0 -1
- package/dist/magma-components/p-1ad03ee9.entry.js +0 -1
- package/dist/magma-components/p-1c4038f7.system.entry.js +0 -1
- package/dist/magma-components/p-2035564c.system.entry.js +0 -1
- package/dist/magma-components/p-2128ce5a.system.entry.js +0 -1
- package/dist/magma-components/p-21ee64ec.entry.js +0 -1
- package/dist/magma-components/p-224d2f55.entry.js +0 -1
- package/dist/magma-components/p-23791e85.system.entry.js +0 -1
- package/dist/magma-components/p-248c1b2c.system.entry.js +0 -1
- package/dist/magma-components/p-249b80a5.entry.js +0 -1
- package/dist/magma-components/p-262daf4f.entry.js +0 -1
- package/dist/magma-components/p-288ce251.entry.js +0 -1
- package/dist/magma-components/p-2a804b82.entry.js +0 -1
- package/dist/magma-components/p-2aff9851.system.entry.js +0 -1
- package/dist/magma-components/p-2b0667f6.system.entry.js +0 -1
- package/dist/magma-components/p-2bd03b3d.system.entry.js +0 -1
- package/dist/magma-components/p-2bfa7ed9.system.entry.js +0 -1
- package/dist/magma-components/p-2c6c80e8.entry.js +0 -1
- package/dist/magma-components/p-2e88e014.system.entry.js +0 -1
- package/dist/magma-components/p-2f5cc981.system.entry.js +0 -1
- package/dist/magma-components/p-31403b12.entry.js +0 -1
- package/dist/magma-components/p-31616d0b.entry.js +0 -1
- package/dist/magma-components/p-33b03c17.system.entry.js +0 -1
- package/dist/magma-components/p-353f30cc.system.entry.js +0 -1
- package/dist/magma-components/p-35482f9d.system.entry.js +0 -1
- package/dist/magma-components/p-35b5889a.system.entry.js +0 -1
- package/dist/magma-components/p-36d9d329.system.entry.js +0 -1
- package/dist/magma-components/p-36fd1ed7.system.entry.js +0 -1
- package/dist/magma-components/p-377c94ee.system.entry.js +0 -1
- package/dist/magma-components/p-385f395d.system.entry.js +0 -1
- package/dist/magma-components/p-39c09a42.system.entry.js +0 -1
- package/dist/magma-components/p-3_AKUQtJ.system.js +0 -1
- package/dist/magma-components/p-3c306ed0.system.entry.js +0 -1
- package/dist/magma-components/p-3de6fa18.entry.js +0 -1
- package/dist/magma-components/p-41da539f.entry.js +0 -1
- package/dist/magma-components/p-422bb9e2.system.entry.js +0 -1
- package/dist/magma-components/p-447c2d1b.entry.js +0 -1
- package/dist/magma-components/p-44e2965d.entry.js +0 -1
- package/dist/magma-components/p-46266f27.entry.js +0 -1
- package/dist/magma-components/p-4630472f.entry.js +0 -1
- package/dist/magma-components/p-4671336c.entry.js +0 -1
- package/dist/magma-components/p-4803d24f.system.entry.js +0 -1
- package/dist/magma-components/p-4a929c1c.entry.js +0 -1
- package/dist/magma-components/p-4bc7756a.system.entry.js +0 -1
- package/dist/magma-components/p-4f8ae676.system.entry.js +0 -1
- package/dist/magma-components/p-50c922ad.system.entry.js +0 -1
- package/dist/magma-components/p-50cdb70c.system.entry.js +0 -1
- package/dist/magma-components/p-52c10dbf.system.entry.js +0 -1
- package/dist/magma-components/p-52e35c13.system.entry.js +0 -1
- package/dist/magma-components/p-56a8f1d0.system.entry.js +0 -1
- package/dist/magma-components/p-5724212b.entry.js +0 -1
- package/dist/magma-components/p-5be1c273.entry.js +0 -1
- package/dist/magma-components/p-5d05fa1a.entry.js +0 -1
- package/dist/magma-components/p-5de4bf4f.entry.js +0 -1
- package/dist/magma-components/p-5e626696.entry.js +0 -1
- package/dist/magma-components/p-5f1532c0.system.entry.js +0 -1
- package/dist/magma-components/p-5fe8c814.entry.js +0 -1
- package/dist/magma-components/p-60e8812c.system.entry.js +0 -17
- package/dist/magma-components/p-611fa0a4.entry.js +0 -1
- package/dist/magma-components/p-61fefe1b.system.entry.js +0 -1
- package/dist/magma-components/p-62c9216f.system.entry.js +0 -1
- package/dist/magma-components/p-652b4e43.entry.js +0 -1
- package/dist/magma-components/p-6a92f533.entry.js +0 -1
- package/dist/magma-components/p-6b3569a0.entry.js +0 -1
- package/dist/magma-components/p-6b9175f1.system.entry.js +0 -1
- package/dist/magma-components/p-6ecfec17.entry.js +0 -1
- package/dist/magma-components/p-6ed096d3.system.entry.js +0 -1
- package/dist/magma-components/p-6ee86191.entry.js +0 -1
- package/dist/magma-components/p-70719b58.entry.js +0 -1
- package/dist/magma-components/p-70e1a436.entry.js +0 -1
- package/dist/magma-components/p-725d9e09.entry.js +0 -1
- package/dist/magma-components/p-726a76f0.entry.js +0 -1
- package/dist/magma-components/p-72d91c6f.system.entry.js +0 -1
- package/dist/magma-components/p-73926a10.entry.js +0 -1
- package/dist/magma-components/p-7499262d.system.entry.js +0 -1
- package/dist/magma-components/p-750214a3.entry.js +0 -1
- package/dist/magma-components/p-7590a160.entry.js +0 -1
- package/dist/magma-components/p-75fa7e6f.system.entry.js +0 -1
- package/dist/magma-components/p-765447d4.system.entry.js +0 -1
- package/dist/magma-components/p-76cb480d.entry.js +0 -1
- package/dist/magma-components/p-79e12ac8.entry.js +0 -1
- package/dist/magma-components/p-7b4b9b88.system.entry.js +0 -1
- package/dist/magma-components/p-7c464f28.entry.js +0 -1
- package/dist/magma-components/p-7d338f59.system.entry.js +0 -1
- package/dist/magma-components/p-81e16f90.system.entry.js +0 -1
- package/dist/magma-components/p-82c6cdb9.system.entry.js +0 -1
- package/dist/magma-components/p-83b01f8e.system.entry.js +0 -1
- package/dist/magma-components/p-8546f46f.system.entry.js +0 -1
- package/dist/magma-components/p-85a2d99d.entry.js +0 -1
- package/dist/magma-components/p-8620f425.entry.js +0 -1
- package/dist/magma-components/p-89581b08.system.entry.js +0 -1
- package/dist/magma-components/p-8964a9fe.entry.js +0 -1
- package/dist/magma-components/p-899cd759.entry.js +0 -1
- package/dist/magma-components/p-8RYXTPXs.js +0 -1
- package/dist/magma-components/p-8b2408b2.entry.js +0 -1
- package/dist/magma-components/p-8b9f6896.entry.js +0 -1
- package/dist/magma-components/p-8bde0c42.entry.js +0 -1
- package/dist/magma-components/p-8d5955ca.system.entry.js +0 -1
- package/dist/magma-components/p-91a1d3d5.entry.js +0 -1
- package/dist/magma-components/p-93538408.system.entry.js +0 -1
- package/dist/magma-components/p-94ff105b.system.entry.js +0 -1
- package/dist/magma-components/p-96f7ec63.entry.js +0 -1
- package/dist/magma-components/p-97144490.entry.js +0 -1
- package/dist/magma-components/p-999b0698.system.entry.js +0 -1
- package/dist/magma-components/p-9e533765.system.entry.js +0 -18
- package/dist/magma-components/p-BMAK4u5Y.system.js +0 -1
- package/dist/magma-components/p-Bh89IjzU.system.js +0 -1
- package/dist/magma-components/p-BudfaWhu.js +0 -1
- package/dist/magma-components/p-C1oxPa_J.js +0 -1
- package/dist/magma-components/p-CAd5312P.js +0 -2
- package/dist/magma-components/p-CJPnuGyH.system.js +0 -1
- package/dist/magma-components/p-DI5DWqw4.system.js +0 -2
- package/dist/magma-components/p-DTZViJWJ.system.js +0 -1
- package/dist/magma-components/p-DcKeJ0td.system.js +0 -6
- package/dist/magma-components/p-DssKRrAV.system.js +0 -1
- package/dist/magma-components/p-MSUJeuJp.js +0 -1
- package/dist/magma-components/p-a24d6d4a.system.entry.js +0 -1
- package/dist/magma-components/p-a24dadaa.system.entry.js +0 -1
- package/dist/magma-components/p-a2b84011.system.entry.js +0 -1
- package/dist/magma-components/p-a2d761d6.entry.js +0 -1
- package/dist/magma-components/p-a379adca.entry.js +0 -1
- package/dist/magma-components/p-a46f7424.system.entry.js +0 -1
- package/dist/magma-components/p-a47708f1.system.entry.js +0 -1
- package/dist/magma-components/p-a4d11055.system.entry.js +0 -1
- package/dist/magma-components/p-a4oAcjYG.js +0 -5
- package/dist/magma-components/p-a5ef9d32.entry.js +0 -18
- package/dist/magma-components/p-a6103622.entry.js +0 -1
- package/dist/magma-components/p-a6b8b861.entry.js +0 -1
- package/dist/magma-components/p-a6bdaa85.entry.js +0 -1
- package/dist/magma-components/p-a716833c.system.entry.js +0 -1
- package/dist/magma-components/p-a877906d.system.entry.js +0 -1
- package/dist/magma-components/p-a8a2d90e.system.entry.js +0 -1
- package/dist/magma-components/p-a92edada.entry.js +0 -1
- package/dist/magma-components/p-aafec5fe.entry.js +0 -1
- package/dist/magma-components/p-abce0c57.system.entry.js +0 -1
- package/dist/magma-components/p-ac2ee475.entry.js +0 -1
- package/dist/magma-components/p-ac5baffa.system.entry.js +0 -1
- package/dist/magma-components/p-ad1ad433.system.entry.js +0 -1
- package/dist/magma-components/p-ae433eb9.entry.js +0 -1
- package/dist/magma-components/p-afaef9a1.entry.js +0 -1
- package/dist/magma-components/p-b257222c.system.entry.js +0 -1
- package/dist/magma-components/p-b472ed3c.entry.js +0 -1
- package/dist/magma-components/p-b4fc19e9.entry.js +0 -1
- package/dist/magma-components/p-b53ef2c1.entry.js +0 -1
- package/dist/magma-components/p-b7dedc9f.entry.js +0 -1
- package/dist/magma-components/p-b97edfb5.entry.js +0 -1
- package/dist/magma-components/p-bc851caf.entry.js +0 -1
- package/dist/magma-components/p-bc8ef479.system.entry.js +0 -9
- package/dist/magma-components/p-bdc54840.system.entry.js +0 -1
- package/dist/magma-components/p-bf29ca5a.entry.js +0 -1
- package/dist/magma-components/p-bfc29d3b.system.entry.js +0 -1
- package/dist/magma-components/p-bff1e84c.system.entry.js +0 -1
- package/dist/magma-components/p-c01c49b6.entry.js +0 -1
- package/dist/magma-components/p-c0296d86.system.entry.js +0 -1
- package/dist/magma-components/p-c036f516.entry.js +0 -1
- package/dist/magma-components/p-c3d8aa52.entry.js +0 -1
- package/dist/magma-components/p-c4e7b103.system.entry.js +0 -1
- package/dist/magma-components/p-c7a0a746.system.entry.js +0 -1
- package/dist/magma-components/p-c92a772e.entry.js +0 -1
- package/dist/magma-components/p-ca09ab1d.system.entry.js +0 -1
- package/dist/magma-components/p-cc9212ce.system.entry.js +0 -1
- package/dist/magma-components/p-cc95225c.system.entry.js +0 -1
- package/dist/magma-components/p-cd49c455.entry.js +0 -1
- package/dist/magma-components/p-d0542487.entry.js +0 -1
- package/dist/magma-components/p-d0dfe659.entry.js +0 -1
- package/dist/magma-components/p-d0eb94ea.system.entry.js +0 -1
- package/dist/magma-components/p-d3e5c4eb.system.entry.js +0 -1
- package/dist/magma-components/p-d4295773.entry.js +0 -1
- package/dist/magma-components/p-d5700423.system.entry.js +0 -1
- package/dist/magma-components/p-d838cb1c.system.entry.js +0 -1
- package/dist/magma-components/p-d9605a5d.system.entry.js +0 -1
- package/dist/magma-components/p-daa8f835.entry.js +0 -1
- package/dist/magma-components/p-db4e2a0b.system.entry.js +0 -1
- package/dist/magma-components/p-de0dac8f.entry.js +0 -1
- package/dist/magma-components/p-de8204f9.entry.js +0 -1
- package/dist/magma-components/p-e0b841e3.entry.js +0 -1
- package/dist/magma-components/p-e35ab355.entry.js +0 -1
- package/dist/magma-components/p-e44e2652.system.entry.js +0 -1
- package/dist/magma-components/p-e48d23f4.system.entry.js +0 -1
- package/dist/magma-components/p-e570aec5.system.entry.js +0 -1
- package/dist/magma-components/p-e57698df.system.entry.js +0 -1
- package/dist/magma-components/p-e669739e.entry.js +0 -1
- package/dist/magma-components/p-e8fa7a07.entry.js +0 -1
- package/dist/magma-components/p-ea2c8dd1.entry.js +0 -1
- package/dist/magma-components/p-ea881c45.system.entry.js +0 -1
- package/dist/magma-components/p-ebfb6963.system.entry.js +0 -1
- package/dist/magma-components/p-eca8523b.system.entry.js +0 -1
- package/dist/magma-components/p-ef142420.system.entry.js +0 -1
- package/dist/magma-components/p-ef56af85.system.entry.js +0 -1
- package/dist/magma-components/p-f0762290.entry.js +0 -1
- package/dist/magma-components/p-f1832c1e.system.entry.js +0 -1
- package/dist/magma-components/p-f4b1974a.entry.js +0 -1
- package/dist/magma-components/p-f7cfc9a7.system.entry.js +0 -1
- package/dist/magma-components/p-f83a9e08.entry.js +0 -1
- package/dist/magma-components/p-f8ee5fec.system.entry.js +0 -1
- package/dist/magma-components/p-f91dab2b.entry.js +0 -1
- package/dist/magma-components/p-fMwnXhio.js +0 -1
- package/dist/magma-components/p-fa61d03c.entry.js +0 -1
- package/dist/magma-components/p-fbf423a7.system.entry.js +0 -1
- package/dist/magma-components/p-fbfb589c.entry.js +0 -1
- package/dist/magma-components/p-fc56d9ae.entry.js +0 -1
- package/dist/magma-components/p-fc862fe2.system.entry.js +0 -1
- package/dist/magma-components/p-fd574e21.entry.js +0 -1
- package/dist/magma-components/p-fd649ac2.entry.js +0 -1
- package/dist/magma-components/p-fed36619.entry.js +0 -1
- package/dist/magma-components/p-oCzRm29V.system.js +0 -1
- package/dist/magma-components/p-ttrRC6OE.js +0 -1
- package/dist/magma-components/p-vYOT2M2B.system.js +0 -1
- package/dist/types/components/mds-accordion/test/mds-accordion.stories.d.ts +0 -40
- package/dist/types/components/mds-accordion-item/test/mds-accordion-item.stories.d.ts +0 -41
- package/dist/types/components/mds-accordion-timer/test/mds-accordion-timer.stories.d.ts +0 -45
- package/dist/types/components/mds-accordion-timer-item/test/mds-accordion-timer-item.stories.d.ts +0 -67
- package/dist/types/components/mds-author/test/mds-author.stories.d.ts +0 -10
- package/dist/types/components/mds-avatar/test/mds-avatar.stories.d.ts +0 -82
- package/dist/types/components/mds-avatar-stack/test/mds-avatar-stack.stories.d.ts +0 -38
- package/dist/types/components/mds-avatar-stack-item/test/mds-avatar-stack-item.stories.d.ts +0 -71
- package/dist/types/components/mds-badge/test/mds-badge.stories.d.ts +0 -56
- package/dist/types/components/mds-banner/test/mds-banner.stories.d.ts +0 -115
- package/dist/types/components/mds-benchmark-bar/test/mds-benchmark-bar.stories.d.ts +0 -85
- package/dist/types/components/mds-bibliography/test/mds-bibliography.stories.d.ts +0 -129
- package/dist/types/components/mds-breadcrumb/test/mds-breadcrumb.stories.d.ts +0 -16
- package/dist/types/components/mds-breadcrumb-item/test/mds-breadcrumb-item.stories.d.ts +0 -26
- package/dist/types/components/mds-button/test/mds-button.stories.d.ts +0 -253
- package/dist/types/components/mds-button-dropdown/test/mds-button-dropdown.stories.d.ts +0 -104
- package/dist/types/components/mds-button-group/test/mds-button-group.stories.d.ts +0 -10
- package/dist/types/components/mds-calendar/test/mds-calendar.stories.d.ts +0 -23
- package/dist/types/components/mds-card/test/mds-card.stories.d.ts +0 -66
- package/dist/types/components/mds-chip/test/mds-chip.stories.d.ts +0 -121
- package/dist/types/components/mds-details/test/mds-details.stories.d.ts +0 -21
- package/dist/types/components/mds-dropdown/test/mds-dropdown.stories.d.ts +0 -275
- package/dist/types/components/mds-emoji/test/mds-emoji.stories.d.ts +0 -19
- package/dist/types/components/mds-entity/test/mds-entity.stories.d.ts +0 -84
- package/dist/types/components/mds-file/test/mds-file.stories.d.ts +0 -145
- package/dist/types/components/mds-file-preview/test/mds-file-preview.stories.d.ts +0 -157
- package/dist/types/components/mds-filter/test/mds-filter.stories.d.ts +0 -56
- package/dist/types/components/mds-filter-item/test/mds-filter-item.stories.d.ts +0 -43
- package/dist/types/components/mds-header/test/mds-header.stories.d.ts +0 -68
- package/dist/types/components/mds-header-bar/test/mds-header-bar.stories.d.ts +0 -23
- package/dist/types/components/mds-help/test/mds-help.stories.d.ts +0 -25
- package/dist/types/components/mds-horizontal-scroll/test/mds-horizontal-scroll.stories.d.ts +0 -57
- package/dist/types/components/mds-hr/test/mds-hr.stories.d.ts +0 -13
- package/dist/types/components/mds-icon/test/mds-icon.stories.d.ts +0 -55
- package/dist/types/components/mds-img/test/mds-img-accessibility.stories.d.ts +0 -93
- package/dist/types/components/mds-img/test/mds-img.stories.d.ts +0 -122
- package/dist/types/components/mds-input/test/mds-input.stories.d.ts +0 -332
- package/dist/types/components/mds-input-date/test/mds-input-date.stories.d.ts +0 -73
- package/dist/types/components/mds-input-date-range/test/mds-input-date-range.stories.d.ts +0 -70
- package/dist/types/components/mds-input-field/test/mds-input-field.stories.d.ts +0 -86
- package/dist/types/components/mds-input-otp/test/mds-input-otp.stories.d.ts +0 -36
- package/dist/types/components/mds-input-range/test/mds-input-range.stories.d.ts +0 -75
- package/dist/types/components/mds-input-select/test/mds-input-select.stories.d.ts +0 -105
- package/dist/types/components/mds-input-switch/test/mds-input-switch.stories.d.ts +0 -195
- package/dist/types/components/mds-input-tip/test/mds-input-tip.stories.d.ts +0 -22
- package/dist/types/components/mds-input-tip-item/test/mds-input-tip.stories.d.ts +0 -22
- package/dist/types/components/mds-input-upload/test/mds-input-upload.stories.d.ts +0 -55
- package/dist/types/components/mds-keyboard/test/mds-keyboard.stories.d.ts +0 -27
- package/dist/types/components/mds-keyboard-key/test/mds-keyboard-key.stories.d.ts +0 -22
- package/dist/types/components/mds-kpi/test/mds-kpi.stories.d.ts +0 -26
- package/dist/types/components/mds-kpi-item/test/mds-kpi-item.stories.d.ts +0 -42
- package/dist/types/components/mds-label/test/mds-label.stories.d.ts +0 -86
- package/dist/types/components/mds-list/test/mds-list.stories.d.ts +0 -7
- package/dist/types/components/mds-list-item/test/mds-list-item.stories.d.ts +0 -38
- package/dist/types/components/mds-mention/test/mds-mention.stories.d.ts +0 -38
- package/dist/types/components/mds-modal/test/mds-modal.stories.d.ts +0 -156
- package/dist/types/components/mds-note/test/mds-note.stories.d.ts +0 -34
- package/dist/types/components/mds-notification/test/mds-notification.stories.d.ts +0 -68
- package/dist/types/components/mds-paginator/test/mds-paginator.stories.d.ts +0 -33
- package/dist/types/components/mds-policy-ai/test/mds-policy.stories.d.ts +0 -83
- package/dist/types/components/mds-pref/test/mds-pref.stories.d.ts +0 -29
- package/dist/types/components/mds-pref-animation/test/mds-pref-animation.stories.d.ts +0 -20
- package/dist/types/components/mds-pref-consumption/test/mds-pref-consumption.stories.d.ts +0 -20
- package/dist/types/components/mds-pref-contrast/test/mds-pref-contrast.stories.d.ts +0 -20
- package/dist/types/components/mds-pref-language/test/mds-pref-language.stories.d.ts +0 -20
- package/dist/types/components/mds-pref-theme/test/mds-pref-theme.stories.d.ts +0 -30
- package/dist/types/components/mds-pref-theme-variant/mds-pref-theme-variant.d.ts +0 -62
- package/dist/types/components/mds-pref-theme-variant/meta/dictionary.d.ts +0 -2
- package/dist/types/components/mds-pref-theme-variant/test/mds-pref-theme-variant.stories.d.ts +0 -30
- package/dist/types/components/mds-pref-theme-variant-item/mds-pref-theme-variant-item.d.ts +0 -35
- package/dist/types/components/mds-price-table/test/mds-price-table.stories.d.ts +0 -10
- package/dist/types/components/mds-price-table-features/test/mds-price-table-features.stories.d.ts +0 -10
- package/dist/types/components/mds-price-table-features-cell/test/mds-price-table-features-cell.stories.d.ts +0 -10
- package/dist/types/components/mds-price-table-header/test/mds-price-table-header.stories.d.ts +0 -7
- package/dist/types/components/mds-price-table-list/test/mds-price-table-list.stories.d.ts +0 -10
- package/dist/types/components/mds-progress/test/mds-progress.stories.d.ts +0 -89
- package/dist/types/components/mds-push-notification/test/mds-push-notification.stories.d.ts +0 -28
- package/dist/types/components/mds-push-notification-item/test/mds-push-notification-item.stories.d.ts +0 -210
- package/dist/types/components/mds-quote/test/mds-quote.stories.d.ts +0 -34
- package/dist/types/components/mds-radial-menu/test/mds-radial-menu.stories.d.ts +0 -123
- package/dist/types/components/mds-radial-menu-item/test/mds-radial-menu-item.stories.d.ts +0 -48
- package/dist/types/components/mds-radial-progress/test/mds-radial-progress.stories.d.ts +0 -68
- package/dist/types/components/mds-separator/test/mds-separator.stories.d.ts +0 -7
- package/dist/types/components/mds-spinner/test/mds-spinner.stories.d.ts +0 -21
- package/dist/types/components/mds-status-bar/test/mds-status-bar.stories.d.ts +0 -34
- package/dist/types/components/mds-stepper-bar/test/mds-stepper-bar.stories.d.ts +0 -45
- package/dist/types/components/mds-stepper-bar-item/test/mds-stepper-bar-item.stories.d.ts +0 -102
- package/dist/types/components/mds-tab/test/mds-tab.stories.d.ts +0 -111
- package/dist/types/components/mds-tab-bar/test/mds-tab-bar.stories.d.ts +0 -7
- package/dist/types/components/mds-tab-bar-item/test/mds-tab-bar-item.stories.d.ts +0 -25
- package/dist/types/components/mds-tab-item/test/mds-tab-item.stories.d.ts +0 -69
- package/dist/types/components/mds-table/test/mds-table.stories.d.ts +0 -63
- package/dist/types/components/mds-text/test/mds-text.stories.d.ts +0 -181
- package/dist/types/components/mds-toast/test/mds-toast.stories.d.ts +0 -59
- package/dist/types/components/mds-tooltip/test/mds-tooltip.stories.d.ts +0 -192
- package/dist/types/components/mds-tree/test/mds-tree-apk.stories.d.ts +0 -16
- package/dist/types/components/mds-tree/test/mds-tree.stories.d.ts +0 -86
- package/dist/types/components/mds-tree-item/test/mds-tree-item.stories.d.ts +0 -48
- package/dist/types/components/mds-url-view/test/mds-url-view.stories.d.ts +0 -63
- package/dist/types/components/mds-usage/test/mds-usage.stories.d.ts +0 -37
- package/dist/types/components/mds-video-wall/test/mds-video-wall.stories.d.ts +0 -119
- package/dist/types/components/mds-zero/test/mds-zero.stories.d.ts +0 -7
- package/dist/types/event-detail/theme-variant.d.ts +0 -5
- package/dist/types/storybook/box-shadows.stories.d.ts +0 -7
- package/dist/types/storybook/color-scale.stories.d.ts +0 -7
- package/dist/types/storybook/components-preview.stories.d.ts +0 -33
- package/dist/types/storybook/example-page.stories.d.ts +0 -7
- package/dist/types/storybook/fouc-hydrated.stories.d.ts +0 -7
- package/dist/types/storybook/input-form.stories.d.ts +0 -7
- package/dist/types/storybook/same-childrend-slot-names.stories.d.ts +0 -7
- package/dist/types/test/file.d.ts +0 -35
- package/dist/types/test/mock.d.ts +0 -2
- /package/dist/collection/{event-detail/theme-variant.js → components/mds-mention/meta/interface.js} +0 -0
- /package/dist/components/{broken-image.js → p-0FAG3rkw.js} +0 -0
- /package/dist/components/{horizontal-rule.js → p-BE8xuIpS.js} +0 -0
- /package/dist/components/{check-circle.js → p-BFhO-KUe.js} +0 -0
- /package/dist/components/{cancel.js → p-BJ8rpzfj.js} +0 -0
- /package/dist/components/{calendar-today.js → p-BVQMG7KJ.js} +0 -0
- /package/dist/components/{arrow-forward.js → p-Bd0uuNDE.js} +0 -0
- /package/dist/components/{keys.js → p-C4ckbXOl.js} +0 -0
- /package/dist/components/{panorama.js → p-CGFwoK_U.js} +0 -0
- /package/dist/components/{aria.js → p-CSCy6TMW.js} +0 -0
- /package/dist/components/{keyboard-arrow-up.js → p-Ccz0jCNB.js} +0 -0
- /package/dist/components/{clsx.js → p-ChV9xqsO.js} +0 -0
- /package/dist/components/{done.js → p-CvUz9jjh.js} +0 -0
- /package/dist/components/{remove.js → p-D17B058a.js} +0 -0
- /package/dist/components/{unit.js → p-D8eZRaSQ.js} +0 -0
- /package/dist/components/{keyboard-arrow-right.js → p-DFyAGAnn.js} +0 -0
- /package/dist/components/{keyboard-arrow-down.js → p-DiWN48aq.js} +0 -0
- /package/dist/components/{browser.js → p-Dje8Mggf.js} +0 -0
- /package/dist/components/{arrow-back.js → p-DnEUG7st.js} +0 -0
- /package/dist/components/{_commonjsHelpers.js → p-E-ZsRS8r.js} +0 -0
- /package/dist/components/{close.js → p-J-ikDhyq.js} +0 -0
- /package/dist/components/{settings.js → p-XQgkfNpn.js} +0 -0
- /package/dist/components/{circle.js → p-lZldSMeV.js} +0 -0
package/dist/documentation.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
|
-
"timestamp": "2026-
|
|
2
|
+
"timestamp": "2026-09-30T11:44:52",
|
|
3
3
|
"compiler": {
|
|
4
4
|
"name": "@stencil/core",
|
|
5
|
-
"version": "4.
|
|
5
|
+
"version": "4.44.2",
|
|
6
6
|
"typescriptVersion": "5.8.3"
|
|
7
7
|
},
|
|
8
8
|
"components": [
|
|
@@ -1015,7 +1015,7 @@
|
|
|
1015
1015
|
}
|
|
1016
1016
|
],
|
|
1017
1017
|
"usage": {
|
|
1018
|
-
"1. Description": "The `<mds-author>` web component is the layout primitive of the Magma Design System for presenting a person's identity: it pairs an avatar with author information (name, role, or any related details). It exposes no props and acts purely as a slotted container, arranging an optional `avatar` slot beside a default content slot.\n\n#### Semantic Behavior\n\n- **Conditional avatar rendering**: The avatar column appears only
|
|
1018
|
+
"1. Description": "The `<mds-author>` web component is the layout primitive of the Magma Design System for presenting a person's identity: it pairs an avatar with author information (name, role, or any related details). It exposes no props and acts purely as a slotted container, arranging an optional `avatar` slot beside a default content slot.\n\n#### Semantic Behavior\n\n- **Conditional avatar rendering**: The avatar column appears only while a direct child assigned to `slot=\"avatar\"` is present, also when it is added after the first render, so omitting it produces no empty column.\n- **Default slot is content, not text**: The default slot is meant to hold structured author information (typically stacked `mds-text` elements for name and role) rather than a single inline label.\n- **Responsive collapse**: Below ~200px wide the avatar stacks above the info and they center, so the same markup adapts from a horizontal row to a compact vertical card.\n- **Compound usage**: It is designed to wrap an `mds-avatar` in the `avatar` slot; the avatar element owns initials/image fallback logic, while `<mds-author>` only positions it.\n\n#### Properties & Visual Configurations\n\nThis component has no properties. All configuration is expressed through its two slots:\n\n- **`avatar` slot**: the leading element, recommended to be an `mds-avatar`. Its presence is what toggles the two-column layout.\n- **default slot**: the trailing block holding the author's textual details, laid out so multiple lines stack cleanly and truncate within the available width.\n\nSee [`projects/stencil/SPEC.md`](../../../../SPEC.md) for the shared compound-component conventions and [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) for the usage contract.\n",
|
|
1019
1019
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-author>` component, ordered from most common to most specialized. Patterns assume a working knowledge of compound-component conventions documented in [`projects/stencil/SPEC.md`](../../../../SPEC.md) and the component catalogue in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md).\n\n#### Full Byline with Avatar\n\nThe canonical form. Place an [`mds-avatar`](../../mds-avatar) in the `avatar` slot and stack the author's name and role in the default slot using [`mds-text`](../../mds-text).\n\n```html\n<mds-author>\n <mds-avatar slot=\"avatar\" initials=\"mg\" src=\"/assets/avatars/mario-gomez.webp\"></mds-avatar>\n <mds-text typography=\"h6\">Mario Gomez</mds-text>\n <mds-text typography=\"caption\">Responsabile editoriale</mds-text>\n</mds-author>\n```\n\n#### Avatar with Initials Fallback\n\nWhen no profile image is available, omit `src` and rely on `initials`. The avatar component derives a deterministic identity color from the initials, keeping people visually distinguishable.\n\n```html\n<mds-author>\n <mds-avatar slot=\"avatar\" initials=\"ag\"></mds-avatar>\n <mds-text typography=\"h6\">Anna Grandi</mds-text>\n <mds-text typography=\"caption\">Giornalista</mds-text>\n</mds-author>\n```\n\n#### Multiple Info Lines\n\nThe default slot is a grid container - any number of stacked lines render cleanly and truncate within the available width.\n\n```html\n<mds-author>\n <mds-avatar slot=\"avatar\" initials=\"fb\" src=\"/assets/avatars/fred-brooks.webp\"></mds-avatar>\n <mds-text typography=\"h6\">Fred Brooks</mds-text>\n <mds-text typography=\"caption\">Ingegnere del software</mds-text>\n <mds-text typography=\"caption\">Dipartimento IT</mds-text>\n</mds-author>\n```\n\n#### Text-Only Author (No Avatar)\n\nOmitting the `avatar` slot entirely collapses the avatar column. No empty space is left - the info block fills the full width.\n\n```html\n<mds-author>\n <mds-text typography=\"h6\">Luca Ferretti</mds-text>\n <mds-text typography=\"caption\">Redattore capo</mds-text>\n</mds-author>\n```\n\n#### Author Card Inside an Article Header\n\n`<mds-author>` is typically embedded inside a card or article header, paired with a date or category label.\n\n```html\n<mds-card>\n <mds-card-header slot=\"header\">\n <mds-author>\n <mds-avatar slot=\"avatar\" initials=\"cs\" src=\"/assets/avatars/chiara-sala.webp\"></mds-avatar>\n <mds-text typography=\"h6\">Chiara Sala</mds-text>\n <mds-text typography=\"caption\">Pubblicato il 3 giugno 2026</mds-text>\n </mds-author>\n </mds-card-header>\n</mds-card>\n```\n\n#### Avatar with Icon for Non-Human Entities\n\nWhen the author represents an organization or system - rather than a person - pass an icon slug to `mds-avatar` instead of initials or a photo.\n\n```html\n<mds-author>\n <mds-avatar slot=\"avatar\" icon=\"mi/baseline/business\"></mds-avatar>\n <mds-text typography=\"h6\">Redazione Magma</mds-text>\n <mds-text typography=\"caption\">Contenuto istituzionale</mds-text>\n</mds-author>\n```\n\n#### Narrow-Container Responsive Behavior\n\n`<mds-author>` uses a CSS container query: inside a container narrower than 200px the avatar stacks above the info and both center automatically. No extra markup is needed - size the parent container to trigger it.\n\n```html\n<!-- In a sidebar widget constrained to ~160px wide, the layout collapses automatically -->\n<aside style=\"width: 160px;\">\n <mds-author>\n <mds-avatar slot=\"avatar\" initials=\"gv\"></mds-avatar>\n <mds-text typography=\"label\">Giulia Verdi</mds-text>\n <mds-text typography=\"caption\">Moderatrice</mds-text>\n </mds-author>\n</aside>\n```\n",
|
|
1020
1020
|
"3. Antipattern": "Common incorrect uses of `<mds-author>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Put Plain Text Directly in the Default Slot\n\nThe default slot is a grid container designed for structured elements like `mds-text`. Bare text nodes render without typography tokens, scale inconsistently, and cannot be truncated reliably.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-author>\n <mds-avatar slot=\"avatar\" initials=\"lr\"></mds-avatar>\n Luca Rossi\n Redattore\n</mds-author>\n\n<!-- ✅ CORRECT -->\n<mds-author>\n <mds-avatar slot=\"avatar\" initials=\"lr\"></mds-avatar>\n <mds-text typography=\"h6\">Luca Rossi</mds-text>\n <mds-text typography=\"caption\">Redattore</mds-text>\n</mds-author>\n```\n\n#### Do Not Place the Avatar in the Default Slot\n\nAssigning an `mds-avatar` without `slot=\"avatar\"` puts it in the text/info region. The component only wires up the two-column layout when a child is assigned to the named `avatar` slot.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-author>\n <mds-avatar initials=\"ab\"></mds-avatar>\n <mds-text typography=\"h6\">Anna Bianchi</mds-text>\n</mds-author>\n\n<!-- ✅ CORRECT -->\n<mds-author>\n <mds-avatar slot=\"avatar\" initials=\"ab\"></mds-avatar>\n <mds-text typography=\"h6\">Anna Bianchi</mds-text>\n</mds-author>\n```\n\n#### Do Not Inline an `<img>` Instead of `mds-avatar`\n\nUsing a raw `<img>` in the avatar slot skips the initials fallback, image-load error handling, and consistent sizing that `mds-avatar` provides.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-author>\n <img slot=\"avatar\" src=\"/assets/foto.jpg\" alt=\"Foto autore\" />\n <mds-text typography=\"h6\">Paolo Neri</mds-text>\n</mds-author>\n\n<!-- ✅ CORRECT -->\n<mds-author>\n <mds-avatar slot=\"avatar\" src=\"/assets/foto.jpg\" initials=\"pn\"></mds-avatar>\n <mds-text typography=\"h6\">Paolo Neri</mds-text>\n</mds-author>\n```\n\n#### Do Not Force Layout via Inline Styles\n\n`<mds-author>` manages its own flex and container-query layout. Overriding `display`, `flex-direction`, or `align-items` on the host breaks the responsive collapse at narrow widths.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-author style=\"flex-direction: column; align-items: flex-start;\">\n <mds-avatar slot=\"avatar\" initials=\"sv\"></mds-avatar>\n <mds-text typography=\"h6\">Sara Vitale</mds-text>\n</mds-author>\n\n<!-- ✅ CORRECT -->\n<!-- Constrain the parent container width to let the built-in container query handle the collapse -->\n<div style=\"width: 160px;\">\n <mds-author>\n <mds-avatar slot=\"avatar\" initials=\"sv\"></mds-avatar>\n <mds-text typography=\"h6\">Sara Vitale</mds-text>\n </mds-author>\n</div>\n```\n\n#### Do Not Use `<mds-author>` as a Generic Flex Row\n\n`<mds-author>` is specifically designed for author bylines. For other avatar-plus-text combinations (entity cards, mention chips, user list rows) use [`mds-entity`](../../mds-entity) or [`mds-mention`](../../mds-mention) instead.\n\n```html\n<!-- 🚫 INCORRECT - using mds-author to display a product or file entry -->\n<mds-author>\n <mds-avatar slot=\"avatar\" icon=\"mi/baseline/folder\"></mds-avatar>\n <mds-text typography=\"h6\">Documento strategico.pdf</mds-text>\n <mds-text typography=\"caption\">1.2 MB</mds-text>\n</mds-author>\n\n<!-- ✅ CORRECT -->\n<mds-entity\n name=\"Documento strategico.pdf\"\n description=\"1.2 MB\"\n icon=\"mi/baseline/folder\"\n></mds-entity>\n```\n"
|
|
1021
1021
|
},
|
|
@@ -1900,7 +1900,7 @@
|
|
|
1900
1900
|
],
|
|
1901
1901
|
"usage": {
|
|
1902
1902
|
"1. Description": "The `<mds-badge>` web component is the Magma Design System's compact status and label indicator, used to attach a short categorical signal (count, state, tag) to other content. It is purely presentational and has no HTML primitive equivalent.\n\n#### Semantic Behavior\n\n- **Text-only content**: The badge is meant to carry a short text string, not markup; the `label` prop is the supported source of that text.\n- **Deprecated default slot**: Slotted text is still read as a legacy fallback, but only when `label` is empty - once `label` is set it always wins. HTML elements or components in the slot are unsupported.\n- **No interactivity**: The component emits no events, has no form association, no focus management, and no disabled/active state - it is a static visual marker.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` / `tone` ladders are defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); `<mds-badge>` consumes them directly and does not add any component-specific values. The default appearance is `variant=\"green\"` with `tone=\"weak\"`.\n\n- **`tone`** selects the chrome treatment: `'weak'` for a subtle tinted fill (the default, best for dense lists and tables), `'strong'` for a saturated high-emphasis fill, and `'outline'` for a bordered, transparent-fill badge that reads as the lightest emphasis.\n\n#### Other behavioral props\n\n- **`typography`** chooses the internal text scale - `'option'` (default) or `'label'` - to align the badge's text size with the surrounding context (e.g. inside a denser table cell vs. a standalone label).\n",
|
|
1903
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-badge>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Badge via `label` Prop\n\nThe canonical form. Use the `label` prop for the badge's text content - it is the preferred source and the slot is deprecated.\n\n```html\n<mds-badge label=\"Attivo\" variant=\"success\" tone=\"weak\"></mds-badge>\n```\n\n#### Variant and Tone for Emphasis\n\nPair the same `variant` with a different `tone` to control visual weight. `tone=\"weak\"` (default) is the lightest fill; `tone=\"strong\"` is a saturated solid; `tone=\"outline\"` adds a visible border with a transparent background.\n\n```html\n<!-- Low emphasis: subtle tinted fill (default) -->\n<mds-badge label=\"Bozza\" variant=\"warning\" tone=\"weak\"></mds-badge>\n\n<!-- High emphasis: solid saturated fill -->\n<mds-badge label=\"Urgente\" variant=\"error\" tone=\"strong\"></mds-badge>\n\n<!-- Minimal emphasis: bordered, no fill -->\n<mds-badge label=\"Archiviato\" variant=\"dark\" tone=\"outline\"></mds-badge>\n```\n\n#### Status Variants\n\nUse status variants (`info`, `success`, `warning`, `error`) to communicate state. Match the variant to the meaning, not to the colour you want.\n\n```html\n<mds-badge label=\"Completato\" variant=\"success\" tone=\"weak\"></mds-badge>\n<mds-badge label=\"In attesa\" variant=\"info\" tone=\"weak\"></mds-badge>\n<mds-badge label=\"Attenzione\" variant=\"warning\" tone=\"weak\"></mds-badge>\n<mds-badge label=\"Errore\" variant=\"error\" tone=\"weak\"></mds-badge>\n```\n\n#### Decorative Label Variants\n\nUse decorative label variants (`green`, `blue`, `violet`, `red`, `orange`, `yellow`, `lime`, `aqua`, `sky`, `orchid`, `purple`, `amaranth`) for categorical tags, topics, or visual grouping that carries no semantic state meaning. The default variant is `green`.\n\n```html\n<mds-badge label=\"Ambiente\" variant=\"green\"></mds-badge>\n<mds-badge label=\"Tecnologia\" variant=\"blue\"></mds-badge>\n<mds-badge label=\"Design\" variant=\"violet\"></mds-badge>\n<mds-badge label=\"Marketing\" variant=\"orange\"></mds-badge>\n```\n\n#### Neutral Variants\n\nUse `variant=\"dark\"` for badges on light backgrounds and `variant=\"light\"` for badges that must appear on dark surfaces.\n\n```html\n<!-- On a light surface -->\n<mds-badge label=\"Categoria\" variant=\"dark\" tone=\"weak\"></mds-badge>\n\n<!-- On a dark or coloured surface -->\n<mds-badge label=\"Categoria\" variant=\"light\" tone=\"strong\"></mds-badge>\n```\n\n#### Typography Scale\n\nUse `typography=\"label\"` when the badge sits inside a denser context (such as a table cell) and the default `\"option\"` size is too large.\n\n```html\n<!-- Default scale - standalone labels, cards, sidebars -->\n<mds-badge label=\"Nuovo\" variant=\"primary\" typography=\"option\"></mds-badge>\n\n<!-- Compact scale - inside tables or tight UI rows -->\n<mds-badge label=\"Nuovo\" variant=\"primary\" typography=\"label\"></mds-badge>\n```\n\n#### Badge Inside a Table Cell\n\n`<mds-badge>` is commonly used as a status indicator inside [`mds-table`](../../mds-table) cells.\n\n```html\n<mds-table>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>\n <mds-badge label=\"Approvato\" variant=\"success\" tone=\"weak\" typography=\"label\"></mds-badge>\n </mds-table-cell>\n <mds-table-cell>\n <mds-badge label=\"In revisione\" variant=\"warning\" tone=\"weak\" typography=\"label\"></mds-badge>\n </mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Badge Inside a File Listing\n\n[`mds-file`](../../mds-file) and [`mds-file-preview`](../../mds-file-preview) render a badge internally to show the file type; you do not slot a badge into them. When adding a badge alongside file content elsewhere, compose it in the surrounding markup.\n\n```html\n<div class=\"file-meta\">\n <mds-file name=\"relazione-2024.pdf\"></mds-file>\n <mds-badge label=\"Firmato\" variant=\"success\" tone=\"weak\" typography=\"label\"></mds-badge>\n</div>\n```\n\n#### Styling Customization\n\nStyle the badge only through its documented `--mds-badge-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.custom-tag mds-badge {\n --mds-badge-background: rgb(var(--label-orchid-09));\n --mds-badge-color: rgb(var(--label-orchid-02));\n --mds-badge-radius: var(--radius-full);\n}\n```\n\nFor `tone=\"outline\"`, also set the border properties:\n\n```css\n.custom-tag mds-badge[tone='outline'] {\n --mds-badge-border-color: rgb(var(--label-orchid-06));\n --mds-badge-border-width: 2px;\n}\n```\n",
|
|
1903
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-badge>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Badge via `label` Prop\n\nThe canonical form. Use the `label` prop for the badge's text content - it is the preferred source and the slot is deprecated.\n\n```html\n<mds-badge label=\"Attivo\" variant=\"success\" tone=\"weak\"></mds-badge>\n```\n\n#### Variant and Tone for Emphasis\n\nPair the same `variant` with a different `tone` to control visual weight. `tone=\"weak\"` (default) is the lightest fill; `tone=\"strong\"` is a saturated solid; `tone=\"outline\"` adds a visible border with a transparent background.\n\n```html\n<!-- Low emphasis: subtle tinted fill (default) -->\n<mds-badge label=\"Bozza\" variant=\"warning\" tone=\"weak\"></mds-badge>\n\n<!-- High emphasis: solid saturated fill -->\n<mds-badge label=\"Urgente\" variant=\"error\" tone=\"strong\"></mds-badge>\n\n<!-- Minimal emphasis: bordered, no fill -->\n<mds-badge label=\"Archiviato\" variant=\"dark\" tone=\"outline\"></mds-badge>\n```\n\n#### Status Variants\n\nUse status variants (`info`, `success`, `warning`, `error`) to communicate state. Match the variant to the meaning, not to the colour you want.\n\n```html\n<mds-badge label=\"Completato\" variant=\"success\" tone=\"weak\"></mds-badge>\n<mds-badge label=\"In attesa\" variant=\"info\" tone=\"weak\"></mds-badge>\n<mds-badge label=\"Attenzione\" variant=\"warning\" tone=\"weak\"></mds-badge>\n<mds-badge label=\"Errore\" variant=\"error\" tone=\"weak\"></mds-badge>\n```\n\n#### Decorative Label Variants\n\nUse decorative label variants (`green`, `blue`, `violet`, `red`, `orange`, `yellow`, `lime`, `aqua`, `sky`, `orchid`, `purple`, `amaranth`) for categorical tags, topics, or visual grouping that carries no semantic state meaning. The default variant is `green`.\n\n```html\n<mds-badge label=\"Ambiente\" variant=\"green\"></mds-badge>\n<mds-badge label=\"Tecnologia\" variant=\"blue\"></mds-badge>\n<mds-badge label=\"Design\" variant=\"violet\"></mds-badge>\n<mds-badge label=\"Marketing\" variant=\"orange\"></mds-badge>\n```\n\n#### Neutral Variants\n\nUse `variant=\"dark\"` for badges on light backgrounds and `variant=\"light\"` for badges that must appear on dark surfaces.\n\n```html\n<!-- On a light surface -->\n<mds-badge label=\"Categoria\" variant=\"dark\" tone=\"weak\"></mds-badge>\n\n<!-- On a dark or coloured surface -->\n<mds-badge label=\"Categoria\" variant=\"light\" tone=\"strong\"></mds-badge>\n```\n\n#### Typography Scale\n\nUse `typography=\"label\"` when the badge sits inside a denser context (such as a table cell) and the default `\"option\"` size is too large.\n\n```html\n<!-- Default scale - standalone labels, cards, sidebars -->\n<mds-badge label=\"Nuovo\" variant=\"primary\" typography=\"option\"></mds-badge>\n\n<!-- Compact scale - inside tables or tight UI rows -->\n<mds-badge label=\"Nuovo\" variant=\"primary\" typography=\"label\"></mds-badge>\n```\n\n#### Badge Inside a Table Cell\n\n`<mds-badge>` is commonly used as a status indicator inside [`mds-table`](../../mds-table) cells.\n\n```html\n<mds-table>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>\n <mds-badge label=\"Approvato\" variant=\"success\" tone=\"weak\" typography=\"label\"></mds-badge>\n </mds-table-cell>\n <mds-table-cell>\n <mds-badge label=\"In revisione\" variant=\"warning\" tone=\"weak\" typography=\"label\"></mds-badge>\n </mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Badge Inside a File Listing\n\n[`mds-file`](../../mds-file) and [`mds-file-preview`](../../mds-file-preview) render a badge internally to show the file type; you do not slot a badge into them. When adding a badge alongside file content elsewhere, compose it in the surrounding markup.\n\n```html\n<div class=\"file-meta\">\n <mds-file name=\"relazione-2024.pdf\"></mds-file>\n <mds-badge label=\"Firmato\" variant=\"success\" tone=\"weak\" typography=\"label\"></mds-badge>\n</div>\n```\n\n#### Styling Customization\n\nStyle the badge only through its documented `--mds-badge-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.custom-tag mds-badge {\n --mds-badge-background: rgb(var(--label-orchid-09));\n --mds-badge-color: rgb(var(--label-orchid-02));\n --mds-badge-radius: var(--radius-full);\n}\n```\n\nFor `tone=\"outline\"`, also set the border properties. The outline badge is always transparent, so `--mds-badge-background` has no effect on it:\n\n```css\n.custom-tag mds-badge[tone='outline'] {\n --mds-badge-border-color: rgb(var(--label-orchid-06));\n --mds-badge-border-width: 2px;\n}\n```\n",
|
|
1904
1904
|
"3. Antipattern": "Common incorrect uses of `<mds-badge>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Put HTML in the Default Slot\n\nThe default slot is deprecated and accepts plain text only; nested elements are stripped or break layout. Use the `label` prop instead.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-badge>\n <strong>Urgente</strong>\n</mds-badge>\n\n<!-- ✅ CORRECT -->\n<mds-badge label=\"Urgente\" variant=\"error\" tone=\"strong\"></mds-badge>\n```\n\n#### Do Not Use the Slot When `label` Is Available\n\nSlotted text still works as a legacy fallback but will be removed in a future release. The `label` prop is the documented API going forward.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-badge>Approvato</mds-badge>\n\n<!-- ✅ CORRECT -->\n<mds-badge label=\"Approvato\" variant=\"success\" tone=\"weak\"></mds-badge>\n```\n\n#### Do Not Apply a `tone` Value Outside the Allowed Set\n\n`<mds-badge>` uses `ToneSmartVariantType`, which allows only `strong`, `weak`, and `outline`. Values like `text` or `box` are not accepted and silently fall back to the default.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-badge label=\"Bozza\" variant=\"warning\" tone=\"text\"></mds-badge>\n<mds-badge label=\"Bozza\" variant=\"warning\" tone=\"box\"></mds-badge>\n\n<!-- ✅ CORRECT -->\n<mds-badge label=\"Bozza\" variant=\"warning\" tone=\"outline\"></mds-badge>\n```\n\n#### Do Not Use Legacy `ghost` or `quiet` Tone Values\n\n`tone=\"ghost\"` and `tone=\"quiet\"` were renamed in Magma 2.0 to `outline` and `text`. Neither name is valid for `<mds-badge>` - use `outline` (the closest equivalent) or `weak`.\n\n```html\n<!-- 🚫 INCORRECT (Magma 1.x naming) -->\n<mds-badge label=\"Archiviato\" tone=\"ghost\" variant=\"dark\"></mds-badge>\n\n<!-- ✅ CORRECT (Magma 2.x) -->\n<mds-badge label=\"Archiviato\" tone=\"outline\" variant=\"dark\"></mds-badge>\n```\n\n#### Do Not Pick a Variant for Its Color Alone\n\n`variant` carries semantic meaning - status variants (`error`, `warning`, `success`, `info`) communicate state; label variants (`green`, `blue`, `violet`, etc.) communicate category. Do not choose a variant just because its color looks right.\n\n```html\n<!-- 🚫 INCORRECT: using \"error\" to get a red tag for a topic, not an error state -->\n<mds-badge label=\"Ruby\" variant=\"error\" tone=\"weak\"></mds-badge>\n\n<!-- ✅ CORRECT: use a decorative label variant for non-state tags -->\n<mds-badge label=\"Ruby\" variant=\"red\" tone=\"weak\"></mds-badge>\n```\n\n#### Do Not Customize via Undocumented Selectors\n\nThe supported customization surface is `--mds-badge-*` CSS custom properties. Targeting shadow-DOM internals via `>>>`, `/deep/`, or undocumented `::part()` names couples your code to implementation details that can change on any release.\n\n```css\n/* 🚫 INCORRECT */\nmds-badge >>> span {\n font-weight: bold;\n letter-spacing: 0.1em;\n}\n\n/* ✅ CORRECT */\nmds-badge {\n --mds-badge-background: rgb(var(--label-violet-09));\n --mds-badge-color: rgb(var(--label-violet-02));\n --mds-badge-radius: var(--radius-full);\n}\n```\n\n#### Do Not Use `<mds-badge>` for Interactive Controls\n\n`<mds-badge>` is purely presentational - it emits no events and has no focus management. For a selectable or dismissible tag, use [`mds-chip`](../../mds-chip) instead.\n\n```html\n<!-- 🚫 INCORRECT: listening to a click on a non-interactive component -->\n<mds-badge label=\"Rimuovi\" variant=\"error\" onclick=\"removeTag()\"></mds-badge>\n\n<!-- ✅ CORRECT: use mds-chip for interactive tag behavior -->\n<mds-chip label=\"Rimuovi\" variant=\"error\" deletable></mds-chip>\n```\n"
|
|
1905
1905
|
},
|
|
1906
1906
|
"props": [
|
|
@@ -2215,7 +2215,7 @@
|
|
|
2215
2215
|
],
|
|
2216
2216
|
"usage": {
|
|
2217
2217
|
"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 [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); 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",
|
|
2218
|
-
"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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.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
|
|
2218
|
+
"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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.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. Use `strong` for maximum contrast, `weak` (default) for subtle background tints, and `box` 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 documented `--mds-banner-*` custom properties. Set them on the host or a parent selector; use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.featured-notice mds-banner {\n --mds-banner-background: rgb(var(--variant-primary-03));\n --mds-banner-color: rgb(var(--tone-kaolin-10));\n --mds-banner-headline-color: rgb(var(--tone-kaolin-10));\n --mds-banner-radius: var(--radius-sm);\n --mds-banner-shadow: 0 4px 16px rgb(var(--tone-neutral-02) / 0.15);\n}\n```\n",
|
|
2219
2219
|
"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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - 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 and will silently fall back to the 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` - overriding them breaks the intentional severity mapping (`error`/`warning` assertive, others polite).\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. Setting it to the string `\"false\"` evaluates as truthy in HTML and shows the close button. 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 `--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-headline-color: rgb(var(--variant-primary-03));\n --mds-banner-radius: var(--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` when the close button is activated (both pointer and keyboard). Listening to the native `click` event may miss keyboard activations and does not bubble out of Shadow DOM reliably.\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"
|
|
2220
2220
|
},
|
|
2221
2221
|
"props": [
|
|
@@ -2446,30 +2446,7 @@
|
|
|
2446
2446
|
"setter": false
|
|
2447
2447
|
}
|
|
2448
2448
|
],
|
|
2449
|
-
"methods": [
|
|
2450
|
-
{
|
|
2451
|
-
"name": "updateLang",
|
|
2452
|
-
"returns": {
|
|
2453
|
-
"type": "Promise<void>",
|
|
2454
|
-
"docs": ""
|
|
2455
|
-
},
|
|
2456
|
-
"complexType": {
|
|
2457
|
-
"signature": "() => Promise<void>",
|
|
2458
|
-
"parameters": [],
|
|
2459
|
-
"references": {
|
|
2460
|
-
"Promise": {
|
|
2461
|
-
"location": "global",
|
|
2462
|
-
"id": "global::Promise"
|
|
2463
|
-
}
|
|
2464
|
-
},
|
|
2465
|
-
"return": "Promise<void>"
|
|
2466
|
-
},
|
|
2467
|
-
"signature": "updateLang() => Promise<void>",
|
|
2468
|
-
"parameters": [],
|
|
2469
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
2470
|
-
"docsTags": []
|
|
2471
|
-
}
|
|
2472
|
-
],
|
|
2449
|
+
"methods": [],
|
|
2473
2450
|
"events": [
|
|
2474
2451
|
{
|
|
2475
2452
|
"event": "mdsBannerClose",
|
|
@@ -2493,11 +2470,6 @@
|
|
|
2493
2470
|
"annotation": "prop",
|
|
2494
2471
|
"docs": "Sets the background-color of the component"
|
|
2495
2472
|
},
|
|
2496
|
-
{
|
|
2497
|
-
"name": "--mds-banner-close-icon-hover-background",
|
|
2498
|
-
"annotation": "prop",
|
|
2499
|
-
"docs": "Sets the background color of the close icon when the mouse is over it"
|
|
2500
|
-
},
|
|
2501
2473
|
{
|
|
2502
2474
|
"name": "--mds-banner-cockade-background",
|
|
2503
2475
|
"annotation": "prop",
|
|
@@ -3306,8 +3278,8 @@
|
|
|
3306
3278
|
],
|
|
3307
3279
|
"usage": {
|
|
3308
3280
|
"1. Description": "The `<mds-breadcrumb>` web component is the navigation-trail container of the Magma Design System. It is a compound parent that arranges a sequence of slotted `<mds-breadcrumb-item>` children into a hierarchical path and adds an optional back-navigation control.\n\n#### Semantic Behavior\n\n- **Compound parent/child**: The default slot accepts only `<mds-breadcrumb-item>` children.\n- **Selection tracking**: When a child is selected it becomes the single current depth and the others are cleared.\n- **Back button**: Unless `hide-back` is set the host renders a leading arrow that steps selection to the previous item; it auto-disables whenever the first item is current.\n- **Change event**: `mdsBreadcrumbChange` fires after any selection change - via a child click or the back arrow - carrying the new index `id` and the originating `caller` item.\n- **Localized back button**: The back button's `title` is resolved per document language (el/en/es/it).\n\n#### Properties & Visual Configurations\n\nThis component exposes a single behavioral prop:\n\n- **`hideBack`** removes the leading arrow control. Leave it off (the default) for multi-level trails where users benefit from a one-tap step backwards; set it for shallow or display-only breadcrumbs where reverse navigation adds no value.\n\nVisual styling (button colors, current-depth color, separator arrow color) is driven by the CSS custom properties documented in [`readme.md`](../readme.md), not by props. The shared `variant` / `tone` / `size` ladders defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system) do not apply here; per-item labels and selection state live on the `<mds-breadcrumb-item>` children.\n",
|
|
3309
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-breadcrumb>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound-component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Navigation Trail\n\nThe canonical form. Slot one `<mds-breadcrumb-item>` per level and mark the current depth with `selected`. The back arrow is shown by default.\n\n```html\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio pratiche\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Pratica 2024/001\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Without the Back Arrow\n\nAdd the `hide-back` attribute for display-only or shallow breadcrumbs where reverse navigation adds no value. The back arrow is shown by default, so this is an explicit opt-out.\n\n```html\n<mds-breadcrumb hide-back>\n <mds-breadcrumb-item label=\"Impostazioni\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Profilo utente\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Listening for Navigation Changes\n\n`mdsBreadcrumbChange` fires whenever a child item is clicked or the back arrow is activated. The detail carries the zero-based `id` string of the newly selected item and the originating `caller` element.\n\n```html\n<mds-breadcrumb id=\"nav\">\n <mds-breadcrumb-item label=\"Dashboard\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Documenti\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Fatture\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<script>\n document.getElementById('nav').addEventListener('mdsBreadcrumbChange', (e) => {\n console.log('Livello selezionato:', e.detail.id);\n console.log('Elemento:', e.detail.caller);\n });\n</script>\n```\n\n#### Programmatic Selection\n\nSet `selected` on the item you want active - the component will deselect the others and update the back button state automatically.\n\n```html\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Progetto Alpha\" selected></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Sprint 3\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Attivita\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Item Label via `label` Prop\n\nAlways prefer the `label` prop on `<mds-breadcrumb-item>` over the default text slot. The prop is reflected as an HTML attribute, enabling CSS attribute selectors and framework bindings.\n\n```html\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Area riservata\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Gestione utenti\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Nuovo utente\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nApply `--mds-breadcrumb-*` vars on the host to retheme the whole trail at once. Use Magma color tokens wrapped in `rgb(var(--<token>))` so dark mode and high-contrast modes keep working. Changes on the parent propagate into the child items because the item vars inherit from the parent vars.\n\n```css\n.sidebar-nav mds-breadcrumb {\n --mds-breadcrumb-button-color: rgb(var(--variant-secondary-03));\n --mds-breadcrumb-button-color-hover: rgb(var(--variant-secondary-01));\n --mds-breadcrumb-button-
|
|
3310
|
-
"3. Antipattern": "Common incorrect uses of `<mds-breadcrumb>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Slot Raw HTML Inside `<mds-breadcrumb>`\n\nThe default slot accepts only `<mds-breadcrumb-item>` elements; slotting arbitrary HTML breaks the internal selection-tracking and back-button logic.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb>\n <a href=\"/home\">Home</a>\n <span>Archivio</span>\n <strong>Documento corrente</strong>\n</mds-breadcrumb>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Documento corrente\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Use `<mds-breadcrumb-item>` Outside `<mds-breadcrumb>`\n\nChild items rely on the parent for ID assignment and selection-state management. Rendering them standalone breaks both keyboard navigation and the change event.\n\n```html\n<!-- 🚫 INCORRECT -->\n<div class=\"my-nav\">\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Sezione\" selected></mds-breadcrumb-item>\n</div>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Sezione\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Pass Text or HTML as `<mds-breadcrumb-item>` Children\n\n`<mds-breadcrumb-item>` has no default slot; the `label` prop is the only way to set the visible text. Text or HTML placed between the tags is ignored and never rendered.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item>\n <strong>Categoria</strong>\n </mds-breadcrumb-item>\n <mds-breadcrumb-item selected>\n <span class=\"active\">Sottocategoria</span>\n </mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Categoria\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Sottocategoria\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Manage Selection State Manually by Toggling Classes\n\nThe parent tracks which item is selected internally; toggling CSS classes or `aria-current` on the host bypasses that logic and leaves the back button in an inconsistent state. Use the `selected` prop instead.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\" class=\"is-active\" aria-current=\"page\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\" selected></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Internal Back Button\n\nThe back button rendered inside `<mds-breadcrumb>` is a private implementation detail. Use the documented `--mds-breadcrumb-*` CSS custom properties to control its appearance.\n\n```css\n/* 🚫 INCORRECT */\nmds-breadcrumb >>> .back {\n background: red;\n}\nmds-breadcrumb::part(back) {\n display: none;\n}\n\n/* ✅ CORRECT */\nmds-breadcrumb {\n --mds-breadcrumb-button-background-disabled: transparent;\n
|
|
3281
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-breadcrumb>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound-component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Navigation Trail\n\nThe canonical form. Slot one `<mds-breadcrumb-item>` per level and mark the current depth with `selected`. The back arrow is shown by default.\n\n```html\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio pratiche\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Pratica 2024/001\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Without the Back Arrow\n\nAdd the `hide-back` attribute for display-only or shallow breadcrumbs where reverse navigation adds no value. The back arrow is shown by default, so this is an explicit opt-out.\n\n```html\n<mds-breadcrumb hide-back>\n <mds-breadcrumb-item label=\"Impostazioni\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Profilo utente\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Listening for Navigation Changes\n\n`mdsBreadcrumbChange` fires whenever a child item is clicked or the back arrow is activated. The detail carries the zero-based `id` string of the newly selected item and the originating `caller` element.\n\n```html\n<mds-breadcrumb id=\"nav\">\n <mds-breadcrumb-item label=\"Dashboard\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Documenti\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Fatture\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<script>\n document.getElementById('nav').addEventListener('mdsBreadcrumbChange', (e) => {\n console.log('Livello selezionato:', e.detail.id);\n console.log('Elemento:', e.detail.caller);\n });\n</script>\n```\n\n#### Programmatic Selection\n\nSet `selected` on the item you want active - the component will deselect the others and update the back button state automatically.\n\n```html\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Progetto Alpha\" selected></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Sprint 3\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Attivita\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Item Label via `label` Prop\n\nAlways prefer the `label` prop on `<mds-breadcrumb-item>` over the default text slot. The prop is reflected as an HTML attribute, enabling CSS attribute selectors and framework bindings.\n\n```html\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Area riservata\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Gestione utenti\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Nuovo utente\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nApply `--mds-breadcrumb-*` vars on the host to retheme the whole trail at once. Use Magma color tokens wrapped in `rgb(var(--<token>))` so dark mode and high-contrast modes keep working. Changes on the parent propagate into the child items because the item vars inherit from the parent vars.\n\n```css\n.sidebar-nav mds-breadcrumb {\n --mds-breadcrumb-button-color: rgb(var(--variant-secondary-03));\n --mds-breadcrumb-button-color-hover: rgb(var(--variant-secondary-01));\n --mds-breadcrumb-button-color-current: rgb(var(--variant-secondary-01));\n --mds-breadcrumb-arrow-depth-color: rgb(var(--variant-secondary-05));\n}\n```\n\n#### Per-Item Styling via `::part(button)`\n\nWhen you need to restyle a single item's inner button beyond what the CSS vars allow, target the documented `::part(button)` on `<mds-breadcrumb-item>`. This is the only supported shadow-part surface on the child component.\n\n```css\nmds-breadcrumb-item[selected]::part(button) {\n font-weight: bold;\n letter-spacing: 0.02em;\n}\n```\n",
|
|
3282
|
+
"3. Antipattern": "Common incorrect uses of `<mds-breadcrumb>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Slot Raw HTML Inside `<mds-breadcrumb>`\n\nThe default slot accepts only `<mds-breadcrumb-item>` elements; slotting arbitrary HTML breaks the internal selection-tracking and back-button logic.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb>\n <a href=\"/home\">Home</a>\n <span>Archivio</span>\n <strong>Documento corrente</strong>\n</mds-breadcrumb>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Documento corrente\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Use `<mds-breadcrumb-item>` Outside `<mds-breadcrumb>`\n\nChild items rely on the parent for ID assignment and selection-state management. Rendering them standalone breaks both keyboard navigation and the change event.\n\n```html\n<!-- 🚫 INCORRECT -->\n<div class=\"my-nav\">\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Sezione\" selected></mds-breadcrumb-item>\n</div>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Sezione\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Pass Text or HTML as `<mds-breadcrumb-item>` Children\n\n`<mds-breadcrumb-item>` has no default slot; the `label` prop is the only way to set the visible text. Text or HTML placed between the tags is ignored and never rendered.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item>\n <strong>Categoria</strong>\n </mds-breadcrumb-item>\n <mds-breadcrumb-item selected>\n <span class=\"active\">Sottocategoria</span>\n </mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Categoria\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Sottocategoria\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Manage Selection State Manually by Toggling Classes\n\nThe parent tracks which item is selected internally; toggling CSS classes or `aria-current` on the host bypasses that logic and leaves the back button in an inconsistent state. Use the `selected` prop instead.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\" class=\"is-active\" aria-current=\"page\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\" selected></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Internal Back Button\n\nThe back button rendered inside `<mds-breadcrumb>` is a private implementation detail. Use the documented `--mds-breadcrumb-*` CSS custom properties to control its appearance.\n\n```css\n/* 🚫 INCORRECT */\nmds-breadcrumb >>> .back {\n background: red;\n}\nmds-breadcrumb::part(back) {\n display: none;\n}\n\n/* ✅ CORRECT */\nmds-breadcrumb {\n --mds-breadcrumb-button-background-disabled: transparent;\n}\n```\n"
|
|
3311
3283
|
},
|
|
3312
3284
|
"props": [
|
|
3313
3285
|
{
|
|
@@ -3343,30 +3315,7 @@
|
|
|
3343
3315
|
"setter": false
|
|
3344
3316
|
}
|
|
3345
3317
|
],
|
|
3346
|
-
"methods": [
|
|
3347
|
-
{
|
|
3348
|
-
"name": "updateLang",
|
|
3349
|
-
"returns": {
|
|
3350
|
-
"type": "Promise<void>",
|
|
3351
|
-
"docs": ""
|
|
3352
|
-
},
|
|
3353
|
-
"complexType": {
|
|
3354
|
-
"signature": "() => Promise<void>",
|
|
3355
|
-
"parameters": [],
|
|
3356
|
-
"references": {
|
|
3357
|
-
"Promise": {
|
|
3358
|
-
"location": "global",
|
|
3359
|
-
"id": "global::Promise"
|
|
3360
|
-
}
|
|
3361
|
-
},
|
|
3362
|
-
"return": "Promise<void>"
|
|
3363
|
-
},
|
|
3364
|
-
"signature": "updateLang() => Promise<void>",
|
|
3365
|
-
"parameters": [],
|
|
3366
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
3367
|
-
"docsTags": []
|
|
3368
|
-
}
|
|
3369
|
-
],
|
|
3318
|
+
"methods": [],
|
|
3370
3319
|
"events": [
|
|
3371
3320
|
{
|
|
3372
3321
|
"event": "mdsBreadcrumbChange",
|
|
@@ -3408,11 +3357,6 @@
|
|
|
3408
3357
|
"annotation": "prop",
|
|
3409
3358
|
"docs": "Sets the background color of the button"
|
|
3410
3359
|
},
|
|
3411
|
-
{
|
|
3412
|
-
"name": "--mds-breadcrumb-button-background-current",
|
|
3413
|
-
"annotation": "prop",
|
|
3414
|
-
"docs": "Sets the background color of the button when it's active"
|
|
3415
|
-
},
|
|
3416
3360
|
{
|
|
3417
3361
|
"name": "--mds-breadcrumb-button-background-disabled",
|
|
3418
3362
|
"annotation": "prop",
|
|
@@ -3433,11 +3377,6 @@
|
|
|
3433
3377
|
"annotation": "prop",
|
|
3434
3378
|
"docs": "Sets the text color of the button when it's active"
|
|
3435
3379
|
},
|
|
3436
|
-
{
|
|
3437
|
-
"name": "--mds-breadcrumb-button-color-disabled",
|
|
3438
|
-
"annotation": "prop",
|
|
3439
|
-
"docs": "Sets the text color of the button when it's disabled, is used for arrow button"
|
|
3440
|
-
},
|
|
3441
3380
|
{
|
|
3442
3381
|
"name": "--mds-breadcrumb-button-color-hover",
|
|
3443
3382
|
"annotation": "prop",
|
|
@@ -3481,7 +3420,7 @@
|
|
|
3481
3420
|
"docsTags": [],
|
|
3482
3421
|
"usage": {
|
|
3483
3422
|
"1. Description": "The `<mds-breadcrumb-item>` web component represents a single navigable depth in a breadcrumb trail. It is a compound child of [`<mds-breadcrumb>`](../../mds-breadcrumb) and renders a clickable label followed by a separator arrow.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-breadcrumb>`; it is not used standalone and the parent's slot should contain only `mds-breadcrumb-item` elements, not mixed child types.\n- **Selection is parent-orchestrated**: Clicking the item emits `mdsBreadcrumbItemSelect` with `{ id, selected }`; the parent then marks the matching item selected and clears the others, so only one item is selected at a time.\n- **Selected item is inert**: While `selected` is true the item cannot be re-activated; non-selected items remain clickable.\n- **Keyboard activation**: The item responds to keyboard activation in addition to pointer clicks.\n- **Decorative separator**: The trailing arrow is decorative and carries no semantic meaning.\n\n#### Properties & Visual Configurations\n\nThis child exposes essentially no visual configuration of its own - appearance is inherited from `<mds-breadcrumb>` and the shared button system, and styling overrides are done through the `--mds-breadcrumb-item-*` CSS custom properties listed in the readme.\n\n- **`label`**: The item's visible text. This is the only way to set the text - the component renders it through an internal `<mds-button>` and exposes no default slot. It matches the `label` prop convention used across Magma components.\n- **`selected`**: Marks this item as the current depth. In normal use you set it on at most one item as the initial state; thereafter the parent manages it in response to navigation. Use it only to seed which depth is active on first render.\n",
|
|
3484
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-breadcrumb-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Breadcrumb Trail\n\nThe canonical form. Place `<mds-breadcrumb-item>` elements as direct children of [`<mds-breadcrumb>`](../../mds-breadcrumb). Use the `label` prop for each step's text.\n\n```html\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Dettaglio documento\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Seeding the Active Depth with `selected`\n\nSet `selected` on the item that represents the user's current location on first render. The parent [`<mds-breadcrumb>`](../../mds-breadcrumb) takes over selection management after that; do not set `selected` on more than one item at a time.\n\n```html\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Documenti\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Listening for Navigation Changes\n\nListen to `mdsBreadcrumbItemSelect` on the item (or on its parent [`<mds-breadcrumb>`](../../mds-breadcrumb) via event bubbling as `mdsBreadcrumbChange`) to react when the user navigates to a different depth.\n\n```html\n<mds-breadcrumb id=\"nav\">\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Pratiche\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Dettaglio\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<script>\n document.querySelector('#nav').addEventListener('mdsBreadcrumbChange', (e) => {\n console.log('profondita selezionata:', e.detail.id);\n });\n</script>\n```\n\n#### Styling the Arrow Separator\n\nOverride `--mds-breadcrumb-item-arrow-depth-color` on the host or a parent selector to recolour the separator icon without touching the button label color. Use Magma color tokens wrapped in `rgb(var(...))` so dark mode keeps working.\n\n```css\n.header-nav mds-breadcrumb-item {\n --mds-breadcrumb-item-arrow-depth-color: rgb(var(--variant-primary-03));\n}\n```\n\n#### Styling Button States\n\nOverride the button color and background tokens to match a custom surface. All three state variants - default, hover, and selected - have dedicated custom properties.\n\n```css\n.sidebar-nav mds-breadcrumb-item {\n --mds-breadcrumb-item-button-color: rgb(var(--tone-neutral-03));\n --mds-breadcrumb-item-button-color-hover: rgb(var(--tone-neutral-01));\n --mds-breadcrumb-item-button-color-selected: rgb(var(--variant-primary-05));\n --mds-breadcrumb-item-button-background-selected: rgb(var(--variant-primary-10));\n}\n```\n\n#### Styling the Internal Button via `::part(button)`\n\nThe internal `<mds-button>` is exposed as `::part(button)`. Use it only when the documented CSS custom properties are insufficient - for example to adjust padding or border radius for a product-specific surface.\n\n```css\n.compact-nav mds-breadcrumb-item::part(button) {\n --mds-button-radius: var(--radius-sm);\n}\n```\n
|
|
3423
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-breadcrumb-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Breadcrumb Trail\n\nThe canonical form. Place `<mds-breadcrumb-item>` elements as direct children of [`<mds-breadcrumb>`](../../mds-breadcrumb). Use the `label` prop for each step's text.\n\n```html\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Dettaglio documento\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Seeding the Active Depth with `selected`\n\nSet `selected` on the item that represents the user's current location on first render. The parent [`<mds-breadcrumb>`](../../mds-breadcrumb) takes over selection management after that; do not set `selected` on more than one item at a time.\n\n```html\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Documenti\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Listening for Navigation Changes\n\nListen to `mdsBreadcrumbItemSelect` on the item (or on its parent [`<mds-breadcrumb>`](../../mds-breadcrumb) via event bubbling as `mdsBreadcrumbChange`) to react when the user navigates to a different depth.\n\n```html\n<mds-breadcrumb id=\"nav\">\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Pratiche\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Dettaglio\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<script>\n document.querySelector('#nav').addEventListener('mdsBreadcrumbChange', (e) => {\n console.log('profondita selezionata:', e.detail.id);\n });\n</script>\n```\n\n#### Styling the Arrow Separator\n\nOverride `--mds-breadcrumb-item-arrow-depth-color` on the host or a parent selector to recolour the separator icon without touching the button label color. Use Magma color tokens wrapped in `rgb(var(...))` so dark mode keeps working.\n\n```css\n.header-nav mds-breadcrumb-item {\n --mds-breadcrumb-item-arrow-depth-color: rgb(var(--variant-primary-03));\n}\n```\n\n#### Styling Button States\n\nOverride the button color and background tokens to match a custom surface. All three state variants - default, hover, and selected - have dedicated custom properties.\n\n```css\n.sidebar-nav mds-breadcrumb-item {\n --mds-breadcrumb-item-button-color: rgb(var(--tone-neutral-03));\n --mds-breadcrumb-item-button-color-hover: rgb(var(--tone-neutral-01));\n --mds-breadcrumb-item-button-color-selected: rgb(var(--variant-primary-05));\n --mds-breadcrumb-item-button-background-selected: rgb(var(--variant-primary-10));\n}\n```\n\n#### Styling the Internal Button via `::part(button)`\n\nThe internal `<mds-button>` is exposed as `::part(button)`. Use it only when the documented CSS custom properties are insufficient - for example to adjust padding or border radius for a product-specific surface.\n\n```css\n.compact-nav mds-breadcrumb-item::part(button) {\n --mds-button-radius: var(--radius-sm);\n}\n```\n",
|
|
3485
3424
|
"3. Antipattern": "Common incorrect uses of `<mds-breadcrumb-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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use Outside `<mds-breadcrumb>`\n\n`<mds-breadcrumb-item>` is a compound child; it communicates with its parent through internal events and relies on the parent to assign IDs, manage selection, and control the back button. Outside the parent it renders an isolated button with no selection management.\n\n```html\n<!-- 🚫 INCORRECT -->\n<nav>\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n</nav>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Pass Text or HTML as Children\n\n`<mds-breadcrumb-item>` has no default slot - it renders its text through an internal `<mds-button>` driven by the `label` prop. Anything placed between the tags (plain text or HTML) is ignored and never rendered. Always use the `label` prop.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb-item>Dettaglio</mds-breadcrumb-item>\n<mds-breadcrumb-item><strong>Dettaglio</strong></mds-breadcrumb-item>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb-item label=\"Dettaglio\"></mds-breadcrumb-item>\n```\n\n#### Do Not Select More Than One Item at Initialisation\n\n`selected` should be set on at most one item as the initial active depth. Marking multiple items selected puts the breadcrumb in an inconsistent state that the parent cannot resolve until the next click.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\" selected></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio\" selected></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Dettaglio\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n <mds-breadcrumb-item label=\"Dettaglio\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Set `selected=\"false\"` to Deselect\n\n`selected` is a boolean attribute. Any non-empty string value - including `\"false\"` - is truthy in HTML and keeps the item selected. Remove the attribute entirely to deselect.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb-item label=\"Home\" selected=\"false\"></mds-breadcrumb-item>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n```\n\n#### Do Not Listen for Native `click` to Track Navigation\n\nThe component emits `mdsBreadcrumbItemSelect` when a step is activated and the parent emits `mdsBreadcrumbChange`. Native `click` events may not bubble out of shadow DOM reliably, and they fire even on the already-selected (inert) item.\n\n```html\n<!-- 🚫 INCORRECT -->\n<script>\n document.querySelector('mds-breadcrumb-item').addEventListener('click', (e) => {\n // may not fire; fires even on the selected/inert item\n });\n</script>\n\n<!-- ✅ CORRECT -->\n<script>\n document.querySelector('mds-breadcrumb').addEventListener('mdsBreadcrumbChange', (e) => {\n console.log('nuovo passo attivo:', e.detail.id);\n });\n</script>\n```\n\n#### Do Not Pierce Shadow DOM to Style Internals\n\nThe supported customization surface is the documented `--mds-breadcrumb-item-*` CSS custom properties and the `::part(button)` export. Targeting internal classes directly couples your code to the shadow DOM implementation and will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-breadcrumb-item >>> .icon {\n fill: red;\n}\n\n/* ✅ CORRECT */\nmds-breadcrumb-item {\n --mds-breadcrumb-item-arrow-depth-color: rgb(var(--variant-primary-03));\n}\n```\n"
|
|
3486
3425
|
},
|
|
3487
3426
|
"props": [
|
|
@@ -3598,26 +3537,6 @@
|
|
|
3598
3537
|
"name": "--mds-breadcrumb-item-button-color-selected",
|
|
3599
3538
|
"annotation": "prop",
|
|
3600
3539
|
"docs": "Sets the text color of the button when it's active"
|
|
3601
|
-
},
|
|
3602
|
-
{
|
|
3603
|
-
"name": "--mds-breadcrumb-item-outline-blur",
|
|
3604
|
-
"annotation": "prop",
|
|
3605
|
-
"docs": "Sets the blur color when the button is blurred via keyboard"
|
|
3606
|
-
},
|
|
3607
|
-
{
|
|
3608
|
-
"name": "--mds-breadcrumb-item-outline-blur-offset",
|
|
3609
|
-
"annotation": "prop",
|
|
3610
|
-
"docs": "Sets the blur offset color when the button is blurred via keyboard"
|
|
3611
|
-
},
|
|
3612
|
-
{
|
|
3613
|
-
"name": "--mds-breadcrumb-item-outline-focus",
|
|
3614
|
-
"annotation": "prop",
|
|
3615
|
-
"docs": "Sets the focus color when the button is focused via keyboard"
|
|
3616
|
-
},
|
|
3617
|
-
{
|
|
3618
|
-
"name": "--mds-breadcrumb-item-outline-focus-offset",
|
|
3619
|
-
"annotation": "prop",
|
|
3620
|
-
"docs": "Sets the focus offset color when the button is focused via keyboard"
|
|
3621
3540
|
}
|
|
3622
3541
|
],
|
|
3623
3542
|
"slots": [],
|
|
@@ -4385,7 +4304,7 @@
|
|
|
4385
4304
|
"mds-note",
|
|
4386
4305
|
"mds-policy-ai",
|
|
4387
4306
|
"mds-pref-language-item",
|
|
4388
|
-
"mds-pref-theme-
|
|
4307
|
+
"mds-pref-theme-item",
|
|
4389
4308
|
"mds-push-notification",
|
|
4390
4309
|
"mds-push-notification-item",
|
|
4391
4310
|
"mds-radial-menu",
|
|
@@ -4475,7 +4394,7 @@
|
|
|
4475
4394
|
"mds-pref-language-item": [
|
|
4476
4395
|
"mds-button"
|
|
4477
4396
|
],
|
|
4478
|
-
"mds-pref-theme-
|
|
4397
|
+
"mds-pref-theme-item": [
|
|
4479
4398
|
"mds-button"
|
|
4480
4399
|
],
|
|
4481
4400
|
"mds-push-notification": [
|
|
@@ -5051,7 +4970,7 @@
|
|
|
5051
4970
|
"docsTags": [
|
|
5052
4971
|
{
|
|
5053
4972
|
"name": "slot",
|
|
5054
|
-
"text": "- Add `mds-button` elements to this slot."
|
|
4973
|
+
"text": "- Add `mds-button` or `mds-button-dropdown` elements to this slot."
|
|
5055
4974
|
}
|
|
5056
4975
|
],
|
|
5057
4976
|
"usage": {
|
|
@@ -5067,7 +4986,7 @@
|
|
|
5067
4986
|
"slots": [
|
|
5068
4987
|
{
|
|
5069
4988
|
"name": "",
|
|
5070
|
-
"docs": "Add `mds-button` elements to this slot."
|
|
4989
|
+
"docs": "Add `mds-button` or `mds-button-dropdown` elements to this slot."
|
|
5071
4990
|
}
|
|
5072
4991
|
],
|
|
5073
4992
|
"parts": [],
|
|
@@ -5089,9 +5008,9 @@
|
|
|
5089
5008
|
}
|
|
5090
5009
|
],
|
|
5091
5010
|
"usage": {
|
|
5092
|
-
"1. Description": "The `<mds-calendar>` web component is the date-selection surface of the Magma Design System: a localized month grid that lets users pick either a single day or a date range. It is the visual engine behind `mds-input-date` and `mds-input-date-range`.\n\n#### Semantic Behavior\n\n- **Range vs. single mode**: `
|
|
5093
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-calendar>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Single-Day Picker\n\
|
|
5094
|
-
"3. Antipattern": "Common incorrect uses of `<mds-calendar>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not
|
|
5011
|
+
"1. Description": "The `<mds-calendar>` web component is the date-selection surface of the Magma Design System: a localized month grid that lets users pick either a single day or a date range. It is the visual engine behind `mds-input-date` and `mds-input-date-range`.\n\n#### Semantic Behavior\n\n- **Range vs. single mode**: range selection is the default; set `singlePicker` to pick one day. In range mode the first click sets the start, the second sets the end, and a third click resets the selection; in single mode each click replaces the prior choice.\n- **Range auto-ordering**: If the second click lands before the current start, the two endpoints are swapped so `startDate` always precedes `endDate`; setting an `endDate` earlier than `startDate` is rejected with a console warning.\n- **Hover preview**: While a range start is set, hovering over cells previews the candidate range live (range mode only).\n- **Min/max bounds**: `min` and `max` mark out-of-range day cells as disabled, blocking their selection.\n- **Multi-view navigation**: The header toggles between the day grid, a month picker, and a year picker; the year view pages in decades while the calendar view pages month by month.\n- **Localization**: Weekday names, month names, and cell titles are formatted from the host's resolved locale (`it`, `en`, `es`, `el`).\n- **Emitted events**: `mdsCalendarChange` fires with `{ startDate, endDate? }` once a selection is complete; `mdsCalendarPreselect` fires alongside it to let preselection chips re-evaluate their state.\n- **Preselection slot**: A `preselection` named slot hosts quick-pick shortcuts. The area appears automatically when the slot has content and `hidePreselection` collapses it.\n\n#### Properties & Visual Configurations\n\nDates are exchanged as ISO 8601 strings (`YYYY-MM-DD`). `startDate` and `endDate` seed and reflect the current selection; on load, a valid `startDate` also determines which month is shown first.\n\n- **`singlePicker`** is the mode switch: omit it for two-ended range selection, set it for single-day pickers. When set, any `endDate` is ignored and cleared with a warning.\n- **`hidePreviousButton`** / **`hideNextButton`** remove one of the header navigation buttons, typically on calendars paired side by side; **`disableMonthYearSelection`** keeps the header on the day grid; **`hideToday`** removes the highlight on today's date.\n- Every boolean prop defaults to `false`: the feature is on until the bare attribute turns it off.\n- **`min`** / **`max`** define the selectable window; days outside it render disabled rather than being hidden.\n\nThis component does not use the shared `variant` / `tone` ladders on its host - those are defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system) and are applied internally to the navigation buttons it renders.\n",
|
|
5012
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-calendar>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Single-Day Picker\n\nSet the bare `single-picker` attribute for a plain single-date selector. `mdsCalendarChange` fires once with `{ startDate }` and no `endDate`. Seed an initial date via `start-date`.\n\n```html\n<mds-calendar single-picker start-date=\"2025-06-10\"></mds-calendar>\n\n<script>\n document.querySelector('mds-calendar').addEventListener('mdsCalendarChange', (e) => {\n console.log('Data selezionata:', e.detail.startDate);\n });\n</script>\n```\n\n#### Range Picker (default mode)\n\nRange selection is the default: omit `single-picker`. The first click sets the start date, the second sets the end date. A third click resets the selection. Preload a range by supplying both `start-date` and `end-date`.\n\n```html\n<mds-calendar start-date=\"2025-09-01\" end-date=\"2025-09-15\"></mds-calendar>\n\n<script>\n document.querySelector('mds-calendar').addEventListener('mdsCalendarChange', (e) => {\n const { startDate, endDate } = e.detail;\n console.log('Intervallo selezionato:', startDate, '-', endDate);\n });\n</script>\n```\n\n#### Restricting the Selectable Window with `min` / `max`\n\nPass ISO 8601 strings to `min` and `max` to mark out-of-range days as disabled. Days outside the window are not hidden - they remain visible but cannot be clicked.\n\n```html\n<mds-calendar\n single-picker\n min=\"2025-01-01\"\n max=\"2025-12-31\"\n></mds-calendar>\n```\n\n#### Navigating to a Specific Month Programmatically\n\nUse the `updateCurrentDate` method to jump the visible month without changing the current selection. Pass any ISO date string that falls within the target month.\n\n```html\n<mds-calendar id=\"cal\" single-picker></mds-calendar>\n\n<script>\n document.querySelector('#cal').updateCurrentDate('2026-03-01');\n</script>\n```\n\n#### Quick-Pick Preselection Shortcuts\n\nThe `preselection` named slot accepts shortcut components such as [`mds-input-date-range-preselection`](../../mds-input-date-range-preselection). When at least one child with the class `date-preselection--has-preselection` is present, the slot panel becomes visible automatically; set `hide-preselection` to keep it collapsed. `mdsCalendarPreselect` fires after each range selection so preselection chips can re-evaluate their active state.\n\n```html\n<mds-calendar start-date=\"2025-09-01\" end-date=\"2025-09-07\">\n <mds-input-date-range-preselection\n slot=\"preselection\"\n ></mds-input-date-range-preselection>\n</mds-calendar>\n```\n\n#### Paired Calendars Without Duplicate Navigation\n\nTwo calendars shown side by side (the pattern used by `mds-input-date-range` on wide viewports) should expose one previous and one next button in total: hide the inner buttons with `hide-previous-button` / `hide-next-button` and lock the header on the day grid with `disable-month-year-selection`, then keep the two `view-date` values one month apart from the `mdsCalendarNavigate` event.\n\n```html\n<mds-calendar id=\"start\" view-date=\"2025-09-01\" hide-next-button disable-month-year-selection></mds-calendar>\n<mds-calendar id=\"end\" view-date=\"2025-10-01\" hide-previous-button disable-month-year-selection></mds-calendar>\n```\n\n#### Listening for Selection Changes\n\nListen on the documented `mdsCalendarChange` event - not the native `change` event - so the handler receives the structured `{ startDate, endDate? }` detail object directly from the Shadow DOM.\n\n```html\n<mds-calendar id=\"picker\" single-picker></mds-calendar>\n\n<script>\n document.querySelector('#picker').addEventListener('mdsCalendarChange', (e) => {\n const { startDate } = e.detail;\n document.querySelector('#output').textContent = 'Scadenza: ' + startDate;\n });\n</script>\n```\n\n#### Embedded inside `mds-input-date` or `mds-input-date-range`\n\n`<mds-calendar>` is the visual engine used internally by [`mds-input-date`](../../mds-input-date) and [`mds-input-date-range`](../../mds-input-date-range). In most product surfaces, reach for those higher-level components. Use `<mds-calendar>` directly only when you need a standalone always-visible date grid without an associated text input.\n\n```html\n<!-- Higher-level: input with calendar overlay -->\n<mds-input-date name=\"scadenza\" label=\"Scadenza\"></mds-input-date>\n\n<!-- Lower-level: always-visible standalone grid -->\n<mds-calendar single-picker></mds-calendar>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nAdjust the calendar appearance only through the documented `--mds-calendar-*` CSS custom properties. Set them on the host element or a parent selector; use Magma color tokens so dark mode and high-contrast modes keep working.\n\n```css\n.booking-widget mds-calendar {\n --mds-calendar-background: rgb(var(--tone-neutral-09));\n --mds-calendar-border-radius: var(--radius-xl);\n --mds-calendar-padding: var(--spacing-500);\n --mds-calendar-cell-gap: var(--gap-100);\n --mds-calendar-day-number-color: rgb(var(--tone-neutral-02));\n --mds-calendar-cell-other-month-visibility: hidden;\n}\n```\n",
|
|
5013
|
+
"3. Antipattern": "Common incorrect uses of `<mds-calendar>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Toggle Single Mode with a Quoted Boolean String\n\n`singlePicker` is a boolean prop that defaults to `false`. In HTML any non-empty attribute value is truthy, so `single-picker=\"false\"` does not restore range mode - it turns single mode on. Use the bare attribute for single mode and omit it for the default range mode; toggle it at runtime by adding/removing the attribute or setting the property in JavaScript.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-calendar single-picker=\"false\"></mds-calendar>\n<mds-calendar single-picker=\"true\"></mds-calendar>\n\n<!-- ✅ CORRECT -->\n<mds-calendar></mds-calendar>\n<mds-calendar single-picker></mds-calendar>\n<script>\n document.querySelector('#cal').singlePicker = false; // back to range mode\n</script>\n```\n\n#### Do Not Set `end-date` When `single-picker` Is Set\n\nWhen `singlePicker` is set, the component rejects `endDate` with a console warning and clears it internally. Setting both `single-picker` and `end-date` is contradictory and produces no visible selection for the end date.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-calendar single-picker start-date=\"2025-06-01\" end-date=\"2025-06-15\"></mds-calendar>\n\n<!-- ✅ CORRECT -->\n<mds-calendar single-picker start-date=\"2025-06-01\"></mds-calendar>\n```\n\n#### Do Not Provide `startDate` After `endDate`\n\nDates must be chronologically ordered: `startDate` must precede `endDate`. If `startDate` is set to a value later than `endDate`, the component logs a console warning and does not apply the update. Always ensure `start-date <= end-date`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-calendar start-date=\"2025-12-31\" end-date=\"2025-12-01\"></mds-calendar>\n\n<!-- ✅ CORRECT -->\n<mds-calendar start-date=\"2025-12-01\" end-date=\"2025-12-31\"></mds-calendar>\n```\n\n#### Do Not Listen for the Native `change` Event\n\n`<mds-calendar>` does not bubble a native `change` event from inside its Shadow DOM. Use the documented `mdsCalendarChange` custom event so the handler reliably receives the structured `{ startDate, endDate? }` payload.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-calendar id=\"cal\"></mds-calendar>\n<script>\n document.querySelector('#cal').addEventListener('change', (e) => {\n console.log(e.target.value); // undefined - wrong event\n });\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-calendar id=\"cal\"></mds-calendar>\n<script>\n document.querySelector('#cal').addEventListener('mdsCalendarChange', (e) => {\n console.log(e.detail.startDate, e.detail.endDate);\n });\n</script>\n```\n\n#### Do Not Place Arbitrary Content in the `preselection` Slot\n\nThe `preselection` slot is designed for preselection shortcut components - not for arbitrary labels, headings, or free text. Placing unsupported elements there disrupts the preset-panel layout and may interfere with the `mdsCalendarPreselect` coordination event.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-calendar>\n <span slot=\"preselection\">Scegli un intervallo rapido</span>\n</mds-calendar>\n\n<!-- ✅ CORRECT -->\n<mds-calendar>\n <mds-input-date-range-preselection\n slot=\"preselection\"\n ></mds-input-date-range-preselection>\n</mds-calendar>\n```\n\n#### Do Not Use `<mds-calendar>` as a Drop-In Replacement for `mds-input-date`\n\n`<mds-calendar>` is not form-associated and emits no `name`/`value` pair for form submission. When you need a date picker tied to a form field, use [`mds-input-date`](../../mds-input-date) (single date) or [`mds-input-date-range`](../../mds-input-date-range) (range) instead.\n\n```html\n<!-- 🚫 INCORRECT -->\n<form action=\"/prenota\" method=\"post\">\n <mds-calendar name=\"check-in\" single-picker></mds-calendar>\n <button type=\"submit\">Prenota</button>\n</form>\n\n<!-- ✅ CORRECT -->\n<form action=\"/prenota\" method=\"post\">\n <mds-input-date name=\"check-in\" label=\"Data di arrivo\"></mds-input-date>\n <button type=\"submit\">Prenota</button>\n</form>\n```\n\n#### Do Not Style Internals via Undocumented `::part()` Selectors\n\nThe only supported customization surface is the set of `--mds-calendar-*` CSS custom properties. Targeting shadow-DOM internals with `::part()` selectors that are not in the documentation couples your code to the implementation and will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-calendar::part(nav) {\n background: red;\n}\nmds-calendar::part(cell) {\n border: 1px solid blue;\n}\n\n/* ✅ CORRECT */\nmds-calendar {\n --mds-calendar-background: rgb(var(--tone-neutral-09));\n --mds-calendar-border-radius: var(--radius-xl);\n --mds-calendar-cell-other-month-visibility: hidden;\n}\n```\n"
|
|
5095
5014
|
},
|
|
5096
5015
|
"props": [
|
|
5097
5016
|
{
|
|
@@ -5163,6 +5082,122 @@
|
|
|
5163
5082
|
"getter": false,
|
|
5164
5083
|
"setter": false
|
|
5165
5084
|
},
|
|
5085
|
+
{
|
|
5086
|
+
"name": "hideNextButton",
|
|
5087
|
+
"type": "boolean",
|
|
5088
|
+
"complexType": {
|
|
5089
|
+
"original": "boolean",
|
|
5090
|
+
"resolved": "boolean",
|
|
5091
|
+
"references": {}
|
|
5092
|
+
},
|
|
5093
|
+
"mutable": false,
|
|
5094
|
+
"attr": "hide-next-button",
|
|
5095
|
+
"reflectToAttr": false,
|
|
5096
|
+
"docs": "If set, the component hides the next navigation button in the calendar header.",
|
|
5097
|
+
"docsTags": [
|
|
5098
|
+
{
|
|
5099
|
+
"name": "default",
|
|
5100
|
+
"text": "false"
|
|
5101
|
+
}
|
|
5102
|
+
],
|
|
5103
|
+
"default": "false",
|
|
5104
|
+
"values": [
|
|
5105
|
+
{
|
|
5106
|
+
"type": "boolean"
|
|
5107
|
+
}
|
|
5108
|
+
],
|
|
5109
|
+
"optional": false,
|
|
5110
|
+
"required": false,
|
|
5111
|
+
"getter": false,
|
|
5112
|
+
"setter": false
|
|
5113
|
+
},
|
|
5114
|
+
{
|
|
5115
|
+
"name": "hidePreselection",
|
|
5116
|
+
"type": "boolean",
|
|
5117
|
+
"complexType": {
|
|
5118
|
+
"original": "boolean",
|
|
5119
|
+
"resolved": "boolean",
|
|
5120
|
+
"references": {}
|
|
5121
|
+
},
|
|
5122
|
+
"mutable": false,
|
|
5123
|
+
"attr": "hide-preselection",
|
|
5124
|
+
"reflectToAttr": false,
|
|
5125
|
+
"docs": "If set, the component hides the preselection area above the calendar view even when the\n`preselection` slot has content.",
|
|
5126
|
+
"docsTags": [
|
|
5127
|
+
{
|
|
5128
|
+
"name": "default",
|
|
5129
|
+
"text": "false"
|
|
5130
|
+
}
|
|
5131
|
+
],
|
|
5132
|
+
"default": "false",
|
|
5133
|
+
"values": [
|
|
5134
|
+
{
|
|
5135
|
+
"type": "boolean"
|
|
5136
|
+
}
|
|
5137
|
+
],
|
|
5138
|
+
"optional": false,
|
|
5139
|
+
"required": false,
|
|
5140
|
+
"getter": false,
|
|
5141
|
+
"setter": false
|
|
5142
|
+
},
|
|
5143
|
+
{
|
|
5144
|
+
"name": "hidePreviousButton",
|
|
5145
|
+
"type": "boolean",
|
|
5146
|
+
"complexType": {
|
|
5147
|
+
"original": "boolean",
|
|
5148
|
+
"resolved": "boolean",
|
|
5149
|
+
"references": {}
|
|
5150
|
+
},
|
|
5151
|
+
"mutable": false,
|
|
5152
|
+
"attr": "hide-previous-button",
|
|
5153
|
+
"reflectToAttr": false,
|
|
5154
|
+
"docs": "If set, the component hides the previous navigation button in the calendar header.",
|
|
5155
|
+
"docsTags": [
|
|
5156
|
+
{
|
|
5157
|
+
"name": "default",
|
|
5158
|
+
"text": "false"
|
|
5159
|
+
}
|
|
5160
|
+
],
|
|
5161
|
+
"default": "false",
|
|
5162
|
+
"values": [
|
|
5163
|
+
{
|
|
5164
|
+
"type": "boolean"
|
|
5165
|
+
}
|
|
5166
|
+
],
|
|
5167
|
+
"optional": false,
|
|
5168
|
+
"required": false,
|
|
5169
|
+
"getter": false,
|
|
5170
|
+
"setter": false
|
|
5171
|
+
},
|
|
5172
|
+
{
|
|
5173
|
+
"name": "hideToday",
|
|
5174
|
+
"type": "boolean",
|
|
5175
|
+
"complexType": {
|
|
5176
|
+
"original": "boolean",
|
|
5177
|
+
"resolved": "boolean",
|
|
5178
|
+
"references": {}
|
|
5179
|
+
},
|
|
5180
|
+
"mutable": false,
|
|
5181
|
+
"attr": "hide-today",
|
|
5182
|
+
"reflectToAttr": false,
|
|
5183
|
+
"docs": "Hides the highlight on today's date in the calendar view.",
|
|
5184
|
+
"docsTags": [
|
|
5185
|
+
{
|
|
5186
|
+
"name": "default",
|
|
5187
|
+
"text": "false"
|
|
5188
|
+
}
|
|
5189
|
+
],
|
|
5190
|
+
"default": "false",
|
|
5191
|
+
"values": [
|
|
5192
|
+
{
|
|
5193
|
+
"type": "boolean"
|
|
5194
|
+
}
|
|
5195
|
+
],
|
|
5196
|
+
"optional": false,
|
|
5197
|
+
"required": false,
|
|
5198
|
+
"getter": false,
|
|
5199
|
+
"setter": false
|
|
5200
|
+
},
|
|
5166
5201
|
{
|
|
5167
5202
|
"name": "hoverDate",
|
|
5168
5203
|
"type": "null | string",
|
|
@@ -5284,65 +5319,7 @@
|
|
|
5284
5319
|
"setter": false
|
|
5285
5320
|
},
|
|
5286
5321
|
{
|
|
5287
|
-
"name": "
|
|
5288
|
-
"type": "boolean",
|
|
5289
|
-
"complexType": {
|
|
5290
|
-
"original": "boolean",
|
|
5291
|
-
"resolved": "boolean",
|
|
5292
|
-
"references": {}
|
|
5293
|
-
},
|
|
5294
|
-
"mutable": false,
|
|
5295
|
-
"attr": "range-picker",
|
|
5296
|
-
"reflectToAttr": false,
|
|
5297
|
-
"docs": "Enables selecting a date range (start and end date) instead of a single date.",
|
|
5298
|
-
"docsTags": [
|
|
5299
|
-
{
|
|
5300
|
-
"name": "default",
|
|
5301
|
-
"text": "true"
|
|
5302
|
-
}
|
|
5303
|
-
],
|
|
5304
|
-
"default": "true",
|
|
5305
|
-
"values": [
|
|
5306
|
-
{
|
|
5307
|
-
"type": "boolean"
|
|
5308
|
-
}
|
|
5309
|
-
],
|
|
5310
|
-
"optional": false,
|
|
5311
|
-
"required": false,
|
|
5312
|
-
"getter": false,
|
|
5313
|
-
"setter": false
|
|
5314
|
-
},
|
|
5315
|
-
{
|
|
5316
|
-
"name": "showNextButton",
|
|
5317
|
-
"type": "boolean",
|
|
5318
|
-
"complexType": {
|
|
5319
|
-
"original": "boolean",
|
|
5320
|
-
"resolved": "boolean",
|
|
5321
|
-
"references": {}
|
|
5322
|
-
},
|
|
5323
|
-
"mutable": false,
|
|
5324
|
-
"attr": "show-next-button",
|
|
5325
|
-
"reflectToAttr": false,
|
|
5326
|
-
"docs": "Shows the next navigation button in the calendar header.",
|
|
5327
|
-
"docsTags": [
|
|
5328
|
-
{
|
|
5329
|
-
"name": "default",
|
|
5330
|
-
"text": "true"
|
|
5331
|
-
}
|
|
5332
|
-
],
|
|
5333
|
-
"default": "true",
|
|
5334
|
-
"values": [
|
|
5335
|
-
{
|
|
5336
|
-
"type": "boolean"
|
|
5337
|
-
}
|
|
5338
|
-
],
|
|
5339
|
-
"optional": false,
|
|
5340
|
-
"required": false,
|
|
5341
|
-
"getter": false,
|
|
5342
|
-
"setter": false
|
|
5343
|
-
},
|
|
5344
|
-
{
|
|
5345
|
-
"name": "showPreselection",
|
|
5322
|
+
"name": "singlePicker",
|
|
5346
5323
|
"type": "boolean",
|
|
5347
5324
|
"complexType": {
|
|
5348
5325
|
"original": "boolean",
|
|
@@ -5350,9 +5327,9 @@
|
|
|
5350
5327
|
"references": {}
|
|
5351
5328
|
},
|
|
5352
5329
|
"mutable": false,
|
|
5353
|
-
"attr": "
|
|
5330
|
+
"attr": "single-picker",
|
|
5354
5331
|
"reflectToAttr": false,
|
|
5355
|
-
"docs": "
|
|
5332
|
+
"docs": "If set, the component selects a single date instead of a date range (start and end date).",
|
|
5356
5333
|
"docsTags": [
|
|
5357
5334
|
{
|
|
5358
5335
|
"name": "default",
|
|
@@ -5370,35 +5347,6 @@
|
|
|
5370
5347
|
"getter": false,
|
|
5371
5348
|
"setter": false
|
|
5372
5349
|
},
|
|
5373
|
-
{
|
|
5374
|
-
"name": "showPreviousButton",
|
|
5375
|
-
"type": "boolean",
|
|
5376
|
-
"complexType": {
|
|
5377
|
-
"original": "boolean",
|
|
5378
|
-
"resolved": "boolean",
|
|
5379
|
-
"references": {}
|
|
5380
|
-
},
|
|
5381
|
-
"mutable": false,
|
|
5382
|
-
"attr": "show-previous-button",
|
|
5383
|
-
"reflectToAttr": false,
|
|
5384
|
-
"docs": "Shows the previous navigation button in the calendar header.",
|
|
5385
|
-
"docsTags": [
|
|
5386
|
-
{
|
|
5387
|
-
"name": "default",
|
|
5388
|
-
"text": "true"
|
|
5389
|
-
}
|
|
5390
|
-
],
|
|
5391
|
-
"default": "true",
|
|
5392
|
-
"values": [
|
|
5393
|
-
{
|
|
5394
|
-
"type": "boolean"
|
|
5395
|
-
}
|
|
5396
|
-
],
|
|
5397
|
-
"optional": false,
|
|
5398
|
-
"required": false,
|
|
5399
|
-
"getter": false,
|
|
5400
|
-
"setter": false
|
|
5401
|
-
},
|
|
5402
5350
|
{
|
|
5403
5351
|
"name": "startDate",
|
|
5404
5352
|
"type": "null | string",
|
|
@@ -5519,31 +5467,9 @@
|
|
|
5519
5467
|
"text": "date the date to display, in ISO format (YYYY-MM-DD)"
|
|
5520
5468
|
}
|
|
5521
5469
|
]
|
|
5522
|
-
}
|
|
5523
|
-
|
|
5524
|
-
|
|
5525
|
-
"returns": {
|
|
5526
|
-
"type": "Promise<void>",
|
|
5527
|
-
"docs": ""
|
|
5528
|
-
},
|
|
5529
|
-
"complexType": {
|
|
5530
|
-
"signature": "() => Promise<void>",
|
|
5531
|
-
"parameters": [],
|
|
5532
|
-
"references": {
|
|
5533
|
-
"Promise": {
|
|
5534
|
-
"location": "global",
|
|
5535
|
-
"id": "global::Promise"
|
|
5536
|
-
}
|
|
5537
|
-
},
|
|
5538
|
-
"return": "Promise<void>"
|
|
5539
|
-
},
|
|
5540
|
-
"signature": "updateLang() => Promise<void>",
|
|
5541
|
-
"parameters": [],
|
|
5542
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
5543
|
-
"docsTags": []
|
|
5544
|
-
}
|
|
5545
|
-
],
|
|
5546
|
-
"events": [
|
|
5470
|
+
}
|
|
5471
|
+
],
|
|
5472
|
+
"events": [
|
|
5547
5473
|
{
|
|
5548
5474
|
"event": "mdsCalendarChange",
|
|
5549
5475
|
"detail": "{ startDate: string; endDate?: string | undefined; }",
|
|
@@ -5629,9 +5555,9 @@
|
|
|
5629
5555
|
"docs": "The color of the day numbers of the current month."
|
|
5630
5556
|
},
|
|
5631
5557
|
{
|
|
5632
|
-
"name": "--mds-calendar-
|
|
5558
|
+
"name": "--mds-calendar-max-width",
|
|
5633
5559
|
"annotation": "prop",
|
|
5634
|
-
"docs": "The
|
|
5560
|
+
"docs": "The maximum inline size of the calendar; it fills its container up to this width."
|
|
5635
5561
|
},
|
|
5636
5562
|
{
|
|
5637
5563
|
"name": "--mds-calendar-padding",
|
|
@@ -6409,7 +6335,7 @@
|
|
|
6409
6335
|
}
|
|
6410
6336
|
],
|
|
6411
6337
|
"usage": {
|
|
6412
|
-
"1. Description": "The `<mds-card-header>` web component is the header region of a [`<mds-card>`](../../mds-card), grouping the card's title, supporting text, and optional inline actions. It carries no styling of its own beyond layout: its job is to occupy the parent card's `header` region and arrange its content alongside any action controls.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-card-header>` must be placed as a direct child of `<mds-card>`; it is not used standalone, and a card expects at most one header alongside its sibling card regions (`mds-card-media`, `mds-card-content`, `mds-card-footer`), not mixed with arbitrary elements.\n- **Self-slotting into the parent**: It automatically lands in the card's `header` region without the author setting any `slot` attribute, and its presence is factored into the card's responsive layout.\n- **Action slot presence**: The dedicated actions wrapper is
|
|
6338
|
+
"1. Description": "The `<mds-card-header>` web component is the header region of a [`<mds-card>`](../../mds-card), grouping the card's title, supporting text, and optional inline actions. It carries no styling of its own beyond layout: its job is to occupy the parent card's `header` region and arrange its content alongside any action controls.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-card-header>` must be placed as a direct child of `<mds-card>`; it is not used standalone, and a card expects at most one header alongside its sibling card regions (`mds-card-media`, `mds-card-content`, `mds-card-footer`), not mixed with arbitrary elements.\n- **Self-slotting into the parent**: It automatically lands in the card's `header` region without the author setting any `slot` attribute, and its presence is factored into the card's responsive layout.\n- **Action slot presence**: The dedicated actions wrapper is shown only while a direct child assigned to the `action` slot exists, also when it is added after the first render, so a header without actions produces no empty action container.\n- **No role/ARIA of its own**: It exposes no implicit role, state, or events; it is a passive layout grouping.\n\n#### Properties & Visual Configurations\n\n`<mds-card-header>` has no configurable properties - it is a pure layout child driven entirely by its two slots:\n\n- **Default (unnamed) slot**: Holds the primary header content (title text, HTML, or components such as a heading element).\n- **`action` slot**: Holds inline action controls, rendered in a separate region next to the header content; `mds-button` is the recommended element here. Provide content to this slot only when the header needs actions, since the wrapper is shown only while children are present.\n",
|
|
6413
6339
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-card-header>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Plain Title in the Default Slot\n\nThe most common use: pass heading text (or a heading element) into the default slot to set the card's title. The header arranges it in the card's top region automatically.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h5\">Dettagli account</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Contenuto principale della card.</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Header with Inline Action\n\nPlace one or more `<mds-button>` elements in the `action` slot when the header needs an inline control. The actions wrapper is only rendered when at least one element is assigned to this slot - omit the slot entirely when no actions are needed.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h5\">Impostazioni notifiche</mds-text>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/edit\"\n aria-label=\"Modifica impostazioni\"\n variant=\"secondary\"\n tone=\"text\"\n ></mds-button>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Gestisci le preferenze di notifica.</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Header with Multiple Actions\n\nAdd multiple elements to the `action` slot when several inline controls are needed. They are rendered in the single actions region next to the header content.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h5\">Documento di progetto</mds-text>\n <mds-button\n slot=\"action\"\n label=\"Modifica\"\n icon=\"mi/baseline/edit\"\n variant=\"primary\"\n tone=\"outline\"\n ></mds-button>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/delete\"\n aria-label=\"Elimina documento\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Specifiche tecniche rev. 3.</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Header with Supporting Text\n\nPass additional descriptive text below the title by adding a second element to the default slot. The header lays both out as a single flex column.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h5\">Report mensile</mds-text>\n <mds-text typography=\"caption\">Aggiornato il 1 giugno 2026</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Riepilogo delle attivita del mese.</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Full Card Composition\n\n`<mds-card-header>` is designed to compose with the other card sub-parts. Each sub-part self-slots into its region; the card infers which regions are present and adjusts its layout accordingly.\n\n```html\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/images/copertina.jpg\" alt=\"Copertina articolo\"></mds-img>\n </mds-card-media>\n <mds-card-header>\n <mds-text typography=\"h4\">Novita dal team</mds-text>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/share\"\n aria-label=\"Condividi\"\n variant=\"secondary\"\n tone=\"text\"\n ></mds-button>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Aggiornamenti sul rilascio di Magma 3.0.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button label=\"Leggi di piu\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Header Without a Title - Using the Action Slot Alone\n\nWhen the card header exists only to host action controls and carries no title text, leave the default slot empty and place the controls in the `action` slot. The component renders just the actions container.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/more-vert\"\n aria-label=\"Altre opzioni\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Scheda con solo azione nell'intestazione.</mds-text>\n </mds-card-content>\n</mds-card>\n```\n",
|
|
6414
6340
|
"3. Antipattern": "Common incorrect uses of `<mds-card-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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-card-header>` Outside `<mds-card>`\n\n`<mds-card-header>` is a compound child; it must be a direct child of `<mds-card>`. Using it standalone renders nothing useful - the host card's slot plumbing drives all layout.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card-header>\n <mds-text typography=\"h5\">Titolo</mds-text>\n</mds-card-header>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h5\">Titolo</mds-text>\n </mds-card-header>\n</mds-card>\n```\n\n#### Do Not Set `slot=\"header\"` Manually on `<mds-card-header>`\n\nThe component sets its own `slot=\"header\"` in its `render()` host binding. Adding the attribute again on the element in the light DOM is redundant and can cause double-slotting in some framework renders.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card>\n <mds-card-header slot=\"header\">\n <mds-text typography=\"h5\">Titolo</mds-text>\n </mds-card-header>\n</mds-card>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h5\">Titolo</mds-text>\n </mds-card-header>\n</mds-card>\n```\n\n#### Do Not Put Action Controls in the Default Slot\n\n`<mds-button>` and other action controls belong in the `action` named slot, not in the default slot. Placing them in the default slot breaks the layout - no actions wrapper is created, and the controls appear inline with title text rather than aligned to the far end.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h5\">Rapporto annuale</mds-text>\n <mds-button label=\"Modifica\" variant=\"primary\"></mds-button>\n </mds-card-header>\n</mds-card>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h5\">Rapporto annuale</mds-text>\n <mds-button slot=\"action\" label=\"Modifica\" variant=\"primary\" tone=\"outline\"></mds-button>\n </mds-card-header>\n</mds-card>\n```\n\n#### Do Not Use a Raw `<div>` as the Card Header Instead of `<mds-card-header>`\n\nUsing a plain `<div slot=\"header\">` bypasses the component's conditional action wrapper, its shadow layout, and the parent's compound-child detection. The component also ensures correct alignment and spacing between title and actions.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card>\n <div slot=\"header\">\n <h5>Riepilogo ordini</h5>\n <button>Modifica</button>\n </div>\n</mds-card>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h5\">Riepilogo ordini</mds-text>\n <mds-button slot=\"action\" label=\"Modifica\" variant=\"primary\" tone=\"outline\"></mds-button>\n </mds-card-header>\n</mds-card>\n```\n\n#### Do Not Invent a Custom `slot` Name on Children of `<mds-card-header>`\n\n`<mds-card-header>` exposes exactly two slots: the default (unnamed) slot and `action`. Assigning any other slot name silently discards the element.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h5\">Dashboard</mds-text>\n <mds-button slot=\"actions\" label=\"Aggiungi\" variant=\"primary\"></mds-button>\n </mds-card-header>\n</mds-card>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h5\">Dashboard</mds-text>\n <mds-button slot=\"action\" label=\"Aggiungi\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-card-header>\n</mds-card>\n```\n"
|
|
6415
6341
|
},
|
|
@@ -6490,7 +6416,7 @@
|
|
|
6490
6416
|
"docsTags": [],
|
|
6491
6417
|
"usage": {
|
|
6492
6418
|
"1. Description": "The `<mds-chip>` web component is the Magma Design System's compact element for representing a discrete piece of information, a filter, a selection, or a removable token. It renders a label with optional leading icon and an optional delete affordance, and can be made interactive (clickable or selectable) to act as a lightweight button-like control rather than a static tag.\n\n#### Semantic Behavior\n\n- **Static by default**: With no interaction props the chip is a passive, non-focusable label; it becomes a focusable, button-like control only when `clickable` is set.\n- **Selectable implies clickable**: Setting `selectable` automatically turns on `clickable`, so a selectable chip is always keyboard- and pointer-interactive.\n- **Selection toggle**: When `selectable`, activating the chip flips `selected`; an unselected chip carries no `selected` attribute (rather than `selected=\"false\"`).\n- **Keyboard activation**: When interactive, Enter/Space activate the chip just like a pointer click.\n- **Delete affordance**: When `deletable`, a trailing delete button is rendered with a localized title (el/en/es/it) and emits the delete event on activation.\n- **Emitted events**: `mdsChipClickLabel` fires on activation for non-selectable chips, `mdsChipSelect` fires (carrying the new `selected` value) for selectable chips, and `mdsChipDelete` fires from the delete button - all carrying the originating event and host element.\n- **Label is text, truncated**: Long labels are clipped on word boundaries rather than wrapping.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` / `tone` ladders are defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); the chip defaults to `variant=\"primary\"` and `tone=\"strong\"`, and accepts only the minimal `'strong'` / `'weak'` tone set.\n\n#### Other behavioral props\n\n- **`clickable`** opts the chip into interactivity (focus, keyboard and click handling) without changing its state on activation - use it for chips that act as actions rather than toggles.\n- **`selectable`** makes the chip a toggle whose `selected` state flips on each activation; pick it for filter/choice chips where the visual selected state matters.\n- **`selected`** drives the selected visual treatment and can be set externally to pre-select a chip; an unselected chip carries no attribute.\n- **`deletable`** adds the trailing cancel button for removable tokens; reserve it for chips the user is meant to dismiss.\n- **`icon`** is an SVG filename slug from the Magma icon library, shown decoratively to the left of the label.\n",
|
|
6493
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-chip>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Static Tag (Label Only)\n\nThe simplest form. Use the required `label` prop to display a read-only tag. With no interaction props the chip is passive and non-focusable.\n\n```html\n<mds-chip label=\"In lavorazione\" variant=\"warning\" tone=\"strong\"></mds-chip>\n```\n\n#### Variant and Tone for Semantic Emphasis\n\nPair the same `variant` with a different `tone` to express importance or category. Do not invent custom colors to dim or saturate.\n\n```html\n<!-- Status chips -->\n<mds-chip label=\"Completato\" variant=\"success\" tone=\"strong\"></mds-chip>\n<mds-chip label=\"In attesa\" variant=\"warning\" tone=\"weak\"></mds-chip>\n<mds-chip label=\"Errore\" variant=\"error\" tone=\"strong\"></mds-chip>\n\n<!-- Decorative label chips -->\n<mds-chip label=\"Natura\" variant=\"green\" tone=\"weak\"></mds-chip>\n<mds-chip label=\"Tecnologia\" variant=\"blue\" tone=\"strong\"></mds-chip>\n```\n\n#### Chip with Leading Icon\n\nReference icons by their filename slug (no `.svg` extension). The icon is rendered decoratively to the left of the label inside a circular badge.\n\n```html\n<mds-chip\n label=\"Animali\"\n icon=\"mi/baseline/pets\"\n variant=\"primary\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Clickable Chip (Action, No Toggle)\n\nUse `clickable` when the chip triggers an action but does not need a persistent selected state. The component adds `role=\"button\"`, focus handling, and keyboard activation. Listen for `mdsChipClickLabel`.\n\n```html\n<mds-chip\n label=\"Apri dettagli\"\n clickable\n icon=\"mi/baseline/open-in-new\"\n variant=\"secondary\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipClickLabel', (e) => {\n console.log('clicked', e.detail.element);\n });\n</script>\n```\n\n#### Selectable Chip (Toggle)\n\nUse `selectable` for filter or choice chips where the visual selected state matters. `selectable` implies `clickable` automatically. Activating the chip flips `selected`; the event `mdsChipSelect` carries the new value in `e.detail.selected`.\n\n```html\n<mds-chip\n label=\"Vegetariano\"\n selectable\n icon=\"mi/baseline/eco\"\n variant=\"success\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipSelect', (e) => {\n console.log('selezionato:', e.detail.selected);\n });\n</script>\n```\n\n#### Pre-selected Chip\n\nSet `selected` externally to initialize a selectable chip in the selected state (e.g. when restoring saved filter state). An unselected chip carries no `selected` attribute.\n\n```html\n<mds-chip\n label=\"Urgente\"\n selectable\n selected\n variant=\"error\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Deletable Chip (Removable Token)\n\nUse `deletable` for chips the user is meant to dismiss - for example tags on an entity or active filters. A trailing cancel button emits `mdsChipDelete` on activation.\n\n```html\n<mds-chip\n label=\"Mario Rossi\"\n deletable\n icon=\"mi/baseline/person\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipDelete', (e) => {\n e.detail.element.remove();\n });\n</script>\n```\n\n#### Fully Interactive Chip\n\nCombine `clickable` (or `selectable`) with `deletable` for chips that can both be activated and removed independently.\n\n```html\n<mds-chip\n label=\"Sport invernali\"\n clickable\n deletable\n icon=\"mi/baseline/downhill-skiing\"\n variant=\"info\"\n tone=\"weak\"\n></mds-chip>\n```\n\n#### Disabled Chip\n\nSet `disabled` to prevent all pointer and keyboard interaction. Do not use `disabled=\"false\"` - remove the attribute to re-enable.\n\n```html\n<mds-chip\n label=\"Non disponibile\"\n disabled\n variant=\"dark\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Styling Customization\n\nStyle the chip only through its documented `--mds-chip-*` CSS custom properties. Set them on the host or a parent selector; use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.
|
|
6419
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-chip>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Static Tag (Label Only)\n\nThe simplest form. Use the required `label` prop to display a read-only tag. With no interaction props the chip is passive and non-focusable.\n\n```html\n<mds-chip label=\"In lavorazione\" variant=\"warning\" tone=\"strong\"></mds-chip>\n```\n\n#### Variant and Tone for Semantic Emphasis\n\nPair the same `variant` with a different `tone` to express importance or category. Do not invent custom colors to dim or saturate.\n\n```html\n<!-- Status chips -->\n<mds-chip label=\"Completato\" variant=\"success\" tone=\"strong\"></mds-chip>\n<mds-chip label=\"In attesa\" variant=\"warning\" tone=\"weak\"></mds-chip>\n<mds-chip label=\"Errore\" variant=\"error\" tone=\"strong\"></mds-chip>\n\n<!-- Decorative label chips -->\n<mds-chip label=\"Natura\" variant=\"green\" tone=\"weak\"></mds-chip>\n<mds-chip label=\"Tecnologia\" variant=\"blue\" tone=\"strong\"></mds-chip>\n```\n\n#### Chip with Leading Icon\n\nReference icons by their filename slug (no `.svg` extension). The icon is rendered decoratively to the left of the label inside a circular badge.\n\n```html\n<mds-chip\n label=\"Animali\"\n icon=\"mi/baseline/pets\"\n variant=\"primary\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Clickable Chip (Action, No Toggle)\n\nUse `clickable` when the chip triggers an action but does not need a persistent selected state. The component adds `role=\"button\"`, focus handling, and keyboard activation. Listen for `mdsChipClickLabel`.\n\n```html\n<mds-chip\n label=\"Apri dettagli\"\n clickable\n icon=\"mi/baseline/open-in-new\"\n variant=\"secondary\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipClickLabel', (e) => {\n console.log('clicked', e.detail.element);\n });\n</script>\n```\n\n#### Selectable Chip (Toggle)\n\nUse `selectable` for filter or choice chips where the visual selected state matters. `selectable` implies `clickable` automatically. Activating the chip flips `selected`; the event `mdsChipSelect` carries the new value in `e.detail.selected`.\n\n```html\n<mds-chip\n label=\"Vegetariano\"\n selectable\n icon=\"mi/baseline/eco\"\n variant=\"success\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipSelect', (e) => {\n console.log('selezionato:', e.detail.selected);\n });\n</script>\n```\n\n#### Pre-selected Chip\n\nSet `selected` externally to initialize a selectable chip in the selected state (e.g. when restoring saved filter state). An unselected chip carries no `selected` attribute.\n\n```html\n<mds-chip\n label=\"Urgente\"\n selectable\n selected\n variant=\"error\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Deletable Chip (Removable Token)\n\nUse `deletable` for chips the user is meant to dismiss - for example tags on an entity or active filters. A trailing cancel button emits `mdsChipDelete` on activation.\n\n```html\n<mds-chip\n label=\"Mario Rossi\"\n deletable\n icon=\"mi/baseline/person\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipDelete', (e) => {\n e.detail.element.remove();\n });\n</script>\n```\n\n#### Fully Interactive Chip\n\nCombine `clickable` (or `selectable`) with `deletable` for chips that can both be activated and removed independently.\n\n```html\n<mds-chip\n label=\"Sport invernali\"\n clickable\n deletable\n icon=\"mi/baseline/downhill-skiing\"\n variant=\"info\"\n tone=\"weak\"\n></mds-chip>\n```\n\n#### Disabled Chip\n\nSet `disabled` to prevent all pointer and keyboard interaction. Do not use `disabled=\"false\"` - remove the attribute to re-enable.\n\n```html\n<mds-chip\n label=\"Non disponibile\"\n disabled\n variant=\"dark\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Styling Customization\n\nStyle the chip only through its documented `--mds-chip-*` CSS custom properties. Set them on the host or a parent selector; use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working. Every token has a `-selected` twin (`--mds-chip-background-selected`, `--mds-chip-border-selected`, `--mds-chip-color-selected`, `--mds-chip-icon-background-selected`, `--mds-chip-icon-color-selected`, `--mds-chip-shadow-selected`); when `selected` is set the component swaps each token for its twin, so override the twin to restyle the selected state.\n\n```css\n.filtri-categoria mds-chip {\n --mds-chip-background: rgb(var(--variant-primary-09));\n --mds-chip-color: rgb(var(--variant-primary-03));\n --mds-chip-icon-background: rgb(var(--variant-primary-06));\n --mds-chip-icon-color: rgb(var(--tone-neutral));\n --mds-chip-background-selected: rgb(var(--variant-primary-04));\n --mds-chip-color-selected: rgb(var(--tone-neutral));\n}\n```\n",
|
|
6494
6420
|
"3. Antipattern": "Common incorrect uses of `<mds-chip>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use a Clickable Chip Without `clickable` or `selectable`\n\nWithout `clickable`, the chip has no `role`, no focus management, and no keyboard activation. Listening for click events on a static chip is a silent accessibility failure.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-chip label=\"Apri\" variant=\"primary\" onclick=\"doSomething()\"></mds-chip>\n\n<!-- ✅ CORRECT -->\n<mds-chip label=\"Apri\" clickable variant=\"primary\"></mds-chip>\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipClickLabel', doSomething);\n</script>\n```\n\n#### Do Not Use `selected` Without `selectable`\n\n`selected` only has visual and semantic meaning when `selectable` is also set. On a non-selectable chip the attribute renders the selected style but the selection can never be toggled and no event fires, misleading users.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-chip label=\"Attivo\" selected variant=\"success\"></mds-chip>\n\n<!-- ✅ CORRECT -->\n<mds-chip label=\"Attivo\" selectable selected variant=\"success\"></mds-chip>\n```\n\n#### Do Not Apply `tone` Values Outside the Minimal Ladder\n\n`mds-chip` accepts only `ToneMinimalVariantType`: `strong` and `weak`. Passing `outline`, `text`, or `box` is invalid and silently falls back to the default tone.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-chip label=\"Categoria\" tone=\"outline\" variant=\"primary\"></mds-chip>\n<mds-chip label=\"Categoria\" tone=\"text\" variant=\"secondary\"></mds-chip>\n\n<!-- ✅ CORRECT -->\n<mds-chip label=\"Categoria\" tone=\"weak\" variant=\"primary\"></mds-chip>\n<mds-chip label=\"Categoria\" tone=\"strong\" variant=\"secondary\"></mds-chip>\n```\n\n#### Do Not Slot Content Into the Chip\n\n`<mds-chip>` has no default or named slots - all content is driven by props (`label`, `icon`, `deletable`). Slotting HTML children is ignored by the Shadow DOM.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-chip>\n <span>Etichetta</span>\n <mds-icon name=\"mi/baseline/close\"></mds-icon>\n</mds-chip>\n\n<!-- ✅ CORRECT -->\n<mds-chip\n label=\"Etichetta\"\n icon=\"mi/baseline/pets\"\n deletable\n variant=\"primary\"\n></mds-chip>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Delete Button\n\nThe inner `mds-button` used for the delete affordance is a Shadow DOM implementation detail. Target it with `>>>` or undocumented `::part()` names will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-chip >>> .button-delete {\n color: red;\n}\n\n/* ✅ CORRECT */\nmds-chip {\n --mds-chip-icon-color: rgb(var(--status-error-04));\n --mds-chip-icon-background: rgb(var(--status-error-09));\n}\n```\n\n#### Do Not Forget to Remove `await`-Pattern Analogue: Removing `selected` by Setting It to `false`\n\nSetting `selected=\"false\"` is treated as truthy in HTML; the correct way to deselect a chip programmatically is to remove the attribute or set the prop to `undefined`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-chip label=\"Filtro\" selectable selected=\"false\" variant=\"primary\"></mds-chip>\n\n<!-- ✅ CORRECT -->\n<mds-chip label=\"Filtro\" selectable variant=\"primary\"></mds-chip>\n```\n\n```js\n// 🚫 INCORRECT\nchipEl.selected = false;\n\n// ✅ CORRECT\nchipEl.selected = undefined;\n```\n\n#### Do Not Use `<mds-chip>` as a Navigation Link\n\n`<mds-chip>` has no `href` prop. Wrapping it in an `<a>` creates a nested interactive element, breaks keyboard semantics, and fails accessibility audits. Use [`mds-button`](../../mds-button) with `href` instead.\n\n```html\n<!-- 🚫 INCORRECT -->\n<a href=\"/categoria/sport\">\n <mds-chip label=\"Sport\" variant=\"primary\"></mds-chip>\n</a>\n\n<!-- ✅ CORRECT -->\n<mds-button\n label=\"Sport\"\n href=\"/categoria/sport\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-button>\n```\n"
|
|
6495
6421
|
},
|
|
6496
6422
|
"props": [
|
|
@@ -6846,30 +6772,7 @@
|
|
|
6846
6772
|
"setter": false
|
|
6847
6773
|
}
|
|
6848
6774
|
],
|
|
6849
|
-
"methods": [
|
|
6850
|
-
{
|
|
6851
|
-
"name": "updateLang",
|
|
6852
|
-
"returns": {
|
|
6853
|
-
"type": "Promise<void>",
|
|
6854
|
-
"docs": ""
|
|
6855
|
-
},
|
|
6856
|
-
"complexType": {
|
|
6857
|
-
"signature": "() => Promise<void>",
|
|
6858
|
-
"parameters": [],
|
|
6859
|
-
"references": {
|
|
6860
|
-
"Promise": {
|
|
6861
|
-
"location": "global",
|
|
6862
|
-
"id": "global::Promise"
|
|
6863
|
-
}
|
|
6864
|
-
},
|
|
6865
|
-
"return": "Promise<void>"
|
|
6866
|
-
},
|
|
6867
|
-
"signature": "updateLang() => Promise<void>",
|
|
6868
|
-
"parameters": [],
|
|
6869
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
6870
|
-
"docsTags": []
|
|
6871
|
-
}
|
|
6872
|
-
],
|
|
6775
|
+
"methods": [],
|
|
6873
6776
|
"events": [
|
|
6874
6777
|
{
|
|
6875
6778
|
"event": "mdsChipClickLabel",
|
|
@@ -6938,14 +6841,24 @@
|
|
|
6938
6841
|
"listeners": [],
|
|
6939
6842
|
"styles": [
|
|
6940
6843
|
{
|
|
6941
|
-
"name": "--mds-chip-
|
|
6844
|
+
"name": "--mds-chip-background",
|
|
6845
|
+
"annotation": "prop",
|
|
6846
|
+
"docs": "Sets the `background-color` of the component"
|
|
6847
|
+
},
|
|
6848
|
+
{
|
|
6849
|
+
"name": "--mds-chip-background-selected",
|
|
6942
6850
|
"annotation": "prop",
|
|
6943
6851
|
"docs": "Sets the `background-color` of the component when it's selected"
|
|
6944
6852
|
},
|
|
6945
6853
|
{
|
|
6946
|
-
"name": "--mds-chip-
|
|
6854
|
+
"name": "--mds-chip-border",
|
|
6947
6855
|
"annotation": "prop",
|
|
6948
|
-
"docs": "Sets the `
|
|
6856
|
+
"docs": "Sets the `border-color` of the component"
|
|
6857
|
+
},
|
|
6858
|
+
{
|
|
6859
|
+
"name": "--mds-chip-border-selected",
|
|
6860
|
+
"annotation": "prop",
|
|
6861
|
+
"docs": "Sets the `border-color` of the component when it's selected"
|
|
6949
6862
|
},
|
|
6950
6863
|
{
|
|
6951
6864
|
"name": "--mds-chip-color",
|
|
@@ -6965,7 +6878,7 @@
|
|
|
6965
6878
|
{
|
|
6966
6879
|
"name": "--mds-chip-icon-background-selected",
|
|
6967
6880
|
"annotation": "prop",
|
|
6968
|
-
"docs": "Sets the `background-color`
|
|
6881
|
+
"docs": "Sets the `background-color` of the icon when the component is selected"
|
|
6969
6882
|
},
|
|
6970
6883
|
{
|
|
6971
6884
|
"name": "--mds-chip-icon-color",
|
|
@@ -6981,6 +6894,16 @@
|
|
|
6981
6894
|
"name": "--mds-chip-opacity-disabled",
|
|
6982
6895
|
"annotation": "prop",
|
|
6983
6896
|
"docs": "Sets the `opacity` of the component when it's disabled"
|
|
6897
|
+
},
|
|
6898
|
+
{
|
|
6899
|
+
"name": "--mds-chip-shadow",
|
|
6900
|
+
"annotation": "prop",
|
|
6901
|
+
"docs": "Sets the `box-shadow` of the component"
|
|
6902
|
+
},
|
|
6903
|
+
{
|
|
6904
|
+
"name": "--mds-chip-shadow-selected",
|
|
6905
|
+
"annotation": "prop",
|
|
6906
|
+
"docs": "Sets the `box-shadow` of the component when it's selected"
|
|
6984
6907
|
}
|
|
6985
6908
|
],
|
|
6986
6909
|
"slots": [],
|
|
@@ -7158,7 +7081,7 @@
|
|
|
7158
7081
|
"filePath": "src/components/mds-dropdown/mds-dropdown.tsx",
|
|
7159
7082
|
"encapsulation": "shadow",
|
|
7160
7083
|
"tag": "mds-dropdown",
|
|
7161
|
-
"readme": "# mds-dropdown\n\n### Best practices of usage\n\nThere are many situations where the component should be placed on the surface of the document:\n\n```html\n<body>\n <mds-dropdown target=\"ui-content\">\n <mds-text>Dropdown contents</mds-text>\n </mds-dropdown>\n <div>\n <mds-text>Deep contents</mds-text>\n <div>\n <mds-text id=\"ui-content\">Deeper contents</mds-text>\n </div>\n </div>\n</body>\n```\n\nThe next use case couldn't be rendered correctly depending by relative/absolute/etc. positioning and `strategy` attribute mix.\n\n```html\n<body>\n <div>\n <mds-text>Deep contents</mds-text>\n <div>\n <mds-text id=\"ui-content\">Deeper contents</mds-text>\n <mds-dropdown target=\"ui-content\">\n <mds-text>Dropdown contents</mds-text>\n </mds-dropdown>\n </div>\n </div>\n</body>\n```\n\nAffected problems:\n\n- Wrong `backdrop` render\n- Wrong `mds-dropdown` positioning\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
|
|
7084
|
+
"readme": "# mds-dropdown\n\n### Best practices of usage\n\nThere are many situations where the component should be placed on the surface of the document:\n\n```html\n<body>\n <mds-dropdown target=\"#ui-content\">\n <mds-text>Dropdown contents</mds-text>\n </mds-dropdown>\n <div>\n <mds-text>Deep contents</mds-text>\n <div>\n <mds-text id=\"ui-content\">Deeper contents</mds-text>\n </div>\n </div>\n</body>\n```\n\nThe next use case couldn't be rendered correctly depending by relative/absolute/etc. positioning and `strategy` attribute mix.\n\n```html\n<body>\n <div>\n <mds-text>Deep contents</mds-text>\n <div>\n <mds-text id=\"ui-content\">Deeper contents</mds-text>\n <mds-dropdown target=\"#ui-content\">\n <mds-text>Dropdown contents</mds-text>\n </mds-dropdown>\n </div>\n </div>\n</body>\n```\n\nAffected problems:\n\n- Wrong `backdrop` render\n- Wrong `mds-dropdown` positioning\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
|
|
7162
7085
|
"docs": "",
|
|
7163
7086
|
"docsTags": [
|
|
7164
7087
|
{
|
|
@@ -7167,8 +7090,8 @@
|
|
|
7167
7090
|
}
|
|
7168
7091
|
],
|
|
7169
7092
|
"usage": {
|
|
7170
|
-
"1. Description": "The `<mds-dropdown>` web component is a floating overlay surface of the Magma Design System that anchors arbitrary slotted content next to an external trigger element. It has no built-in trigger of its own: it attaches to a separate caller resolved via `target` and positions, flips and shifts itself around that element.\n\n#### Semantic Behavior\n\n- **Caller binding**: The dropdown does not render a trigger; it resolves its caller from the `target` selector and wires the chosen interaction onto that external element. Changing `target` re-binds the caller.\n- **Visibility is the single source of truth**: The `visible` prop drives the whole lifecycle - it positions the floating element, optionally shows the backdrop, and emits the events; setting it back to `false` dismisses it.\n- **Outside-click dismissal**: While open, clicking outside both the host and the caller closes the dropdown.\n- **Escape to close**: Pressing Escape hides the dropdown.\n- **Backdrop**: When `backdrop` is set, a backdrop is shown while the dropdown is visible and removed on close.\n- **Emitted events**: `mdsDropdownChange` fires on every visibility transition; `mdsDropdownVisible` and `mdsDropdownHide` fire on open and close respectively. Each detail carries the resolved `caller` and the current `visible` state.\n- **Default slot is the panel content**: Anything in the default slot (text, HTML, or other components) is the surface shown when the dropdown is triggered.\n\n#### Properties & Visual Configurations\n\n- **`interaction`** decides how the caller opens the panel: `'click'` toggles on caller click (with outside-click and Escape dismissal), `'mouseover'` opens on hover and closes on mouse leave, and `'none'` disables all automatic wiring so visibility is controlled programmatically through `visible`.\n- **`target`** (required) is the CSS selector of the external element the dropdown attaches to and positions against.\n\n#### Other behavioral props\n\n- **`placement`** sets the preferred side relative to the caller; the best side is chosen automatically by default (**`disableAutoPlacement`** opts out and pins to `placement`), **`flip`** allows falling back to the opposite side when space runs out, and the panel is shifted to stay inside the viewport with a safe margin by default — **`disableShift`** opts out of this and **`shiftPadding`** tunes the margin.\n- **`offset`** controls the gap between the panel and the caller; the pointer toward the caller is shown by default (**`hideArrow`** removes it) and **`arrowPadding`** insets it from the panel edges.\n- the panel tracks the caller smoothly as the page scrolls by default (**`disableSmooth`** opts out); **`strategy`** chooses the CSS positioning mode (`'absolute'` vs `'fixed'`) and **`zIndex`** sets the stacking order.\n",
|
|
7171
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-dropdown>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Dropdown Menu\n\nThe minimal required setup: a trigger element with a unique `id` and a `<mds-dropdown>` with `target` pointing at it. The dropdown binds to the caller on `click` by default and dismisses on outside-click or Escape.\n\n```html\n<mds-button id=\"menu-utente\" label=\"Profilo\" icon=\"mi/baseline/account-circle\" variant=\"secondary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#menu-utente\">\n <mds-button icon=\"mi/baseline/settings\" variant=\"dark\" tone=\"text\" label=\"Impostazioni account\"></mds-button>\n <mds-button icon=\"mi/baseline/logout\" variant=\"error\" tone=\"text\" label=\"Esci\"></mds-button>\n</mds-dropdown>\n```\n\n#### Dropdown with Arrow Pointer\n\nThe arrow pointer is shown by default to visually connect the panel to its caller; add `hide-arrow` to remove it. Adjust `arrow-padding` when the panel is narrow and the arrow would clip the rounded corners.\n\n```html\n<mds-button id=\"aiuto-contestuale\" label=\"Aiuto\" icon=\"mi/baseline/help-outline\" variant=\"secondary\" tone=\"outline\"></mds-button>\n\n<mds-dropdown target=\"#aiuto-contestuale\" arrow-padding=\"16\">\n <mds-text typography=\"h6\">Come funziona?</mds-text>\n <mds-text typography=\"detail\">Seleziona un campo per vedere la guida contestuale.</mds-text>\n</mds-dropdown>\n```\n\n#### Dropdown with Backdrop\n\nUse `backdrop` to dim the rest of the page while the panel is open. This is appropriate for panels with a higher modal weight, such as user-account menus or multi-step pickers.\n\n```html\n<mds-button id=\"selezione-filtri\" label=\"Filtra risultati\" icon=\"mi/baseline/filter-list\" variant=\"primary\"></mds-button>\n\n<mds-dropdown target=\"#selezione-filtri\" backdrop>\n <mds-text typography=\"h6\">Filtra per categoria</mds-text>\n <mds-filter>\n <mds-filter-item label=\"Documenti\"></mds-filter-item>\n <mds-filter-item label=\"Immagini\"></mds-filter-item>\n <mds-filter-item label=\"Video\"></mds-filter-item>\n </mds-filter>\n</mds-dropdown>\n```\n\n#### Mouseover Interaction\n\nSet `interaction=\"mouseover\"` for navigation mega-menus or info tooltips that should open on hover. The component adds a configurable delay (default 0.5 s, controlled by `--mds-dropdown-mouseover-delay`) before opening and closing.\n\n```html\n<mds-button id=\"info-progetto\" label=\"Dettagli progetto\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-dropdown target=\"#info-progetto\" interaction=\"mouseover\">\n <mds-entity icon=\"mi/baseline/folder\">\n <mds-text>Progetto Alfa - In corso</mds-text>\n </mds-entity>\n</mds-dropdown>\n```\n\n#### Programmatic Control via `visible`\n\nSet `interaction=\"none\"` to disable automatic wiring and drive visibility yourself. This is useful when the trigger logic lives in app code - for example, opening on a keyboard shortcut or a programmatic state change.\n\n```html\n<mds-button id=\"apri-manuale\" label=\"Apri pannello\" variant=\"secondary\"></mds-button>\n\n<mds-dropdown id=\"pannello-opzioni\" target=\"#apri-manuale\" interaction=\"none\">\n <mds-text typography=\"detail\">Pannello gestito dal codice applicativo.</mds-text>\n</mds-dropdown>\n\n<script>\n const dropdown = document.querySelector('#pannello-opzioni');\n document.querySelector('#apri-manuale').addEventListener('click', () => {\n dropdown.visible = !dropdown.visible;\n });\n</script>\n```\n\n#### Placement and Auto-Placement\n\nUse `placement` to anchor the panel to a specific side of the caller. Auto-placement is on by default, letting the component choose the best available side based on viewport space; add `disable-auto-placement` to pin the panel strictly to `placement`.\n\n```html\n<!-- Pinned right-start placement (auto-placement disabled) -->\n<mds-button id=\"azioni-riga\" label=\"Azioni\" icon=\"mi/baseline/more-vert\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-dropdown target=\"#azioni-riga\" placement=\"right-start\" disable-auto-placement>\n <mds-button icon=\"mi/baseline/edit\" variant=\"dark\" tone=\"text\" label=\"Modifica\"></mds-button>\n <mds-button icon=\"mi/baseline/delete\" variant=\"error\" tone=\"text\" label=\"Elimina\"></mds-button>\n</mds-dropdown>\n\n<!-- Auto-placement (default) for constrained viewports -->\n<mds-button id=\"opzioni-voce\" label=\"Opzioni\" variant=\"secondary\" tone=\"weak\"></mds-button>\n<mds-dropdown target=\"#opzioni-voce\">\n <mds-button label=\"Duplica\" icon=\"mi/baseline/content-copy\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-dropdown>\n```\n\n#### Flip and Shift for Viewport Safety\n\nEnable `flip` to let the panel jump to the opposite side when there is not enough space in the preferred direction. Shifting the panel to keep it inside the viewport is on by default; tune the safe margin with `shift-padding` (or set `disable-shift` to opt out).\n\n```html\n<mds-button id=\"btn-edge\" label=\"Vicino al bordo\" variant=\"primary\"></mds-button>\n\n<mds-dropdown target=\"#btn-edge\" placement=\"top\" flip shift-padding=\"16\">\n <mds-text typography=\"detail\">Questo pannello si sposta automaticamente se manca spazio.</mds-text>\n</mds-dropdown>\n```\n\n#### Listening to Visibility Events\n\nListen for `mdsDropdownVisible`, `mdsDropdownHide`, or `mdsDropdownChange` to react to open/close transitions. Each event detail contains `caller` (the resolved trigger element) and `visible` (the new state).\n\n```html\n<mds-button id=\"btn-notifica\" label=\"Notifiche\" icon=\"mi/baseline/notifications\" variant=\"secondary\"></mds-button>\n\n<mds-dropdown id=\"pannello-notifiche\" target=\"#btn-notifica\">\n <mds-text typography=\"detail\">Nessuna nuova notifica.</mds-text>\n</mds-dropdown>\n\n<script>\n document.querySelector('#pannello-notifiche').addEventListener('mdsDropdownVisible', (e) => {\n console.log('Aperto. Trigger:', e.detail.caller);\n });\n document.querySelector('#pannello-notifiche').addEventListener('mdsDropdownHide', () => {\n console.log('Chiuso.');\n });\n</script>\n```\n\n#### Strategy `fixed` Inside Scrolling or Stacked Containers\n\nUse `strategy=\"fixed\"` when the dropdown is placed inside a scroll container, a sticky header, or a modal. With `strategy=\"absolute\"` (the default) the panel may be clipped by `overflow: hidden` ancestors.\n\n```html\n<!-- Inside a modal or a sticky nav - use fixed positioning -->\n<mds-button id=\"menu-header\" label=\"Menu\" variant=\"secondary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#menu-header\" strategy=\"fixed\">\n <mds-button label=\"Pagina principale\" icon=\"mi/baseline/home\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Impostazioni\" icon=\"mi/baseline/settings\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-dropdown>\n```\n\n#### DOM Placement at the Document Root\n\nPlace `<mds-dropdown>` as a direct child of `<body>` (or as close as possible to the root) when the caller lives deep inside a stacking context. Nesting the dropdown inside the same transformed or `overflow: hidden` ancestor as the caller can break positioning and backdrop rendering.\n\n```html\n<body>\n <!-- Trigger lives inside a complex layout -->\n <div class=\"app-layout\">\n <nav>\n <mds-button id=\"btn-profilo\" label=\"Profilo\" variant=\"secondary\"></mds-button>\n </nav>\n </div>\n\n <!-- Dropdown is a sibling of the layout root, not nested inside it -->\n <mds-dropdown target=\"#btn-profilo\" strategy=\"fixed\" backdrop>\n <mds-text typography=\"h6\">Mario Rossi</mds-text>\n <mds-button label=\"Esci\" icon=\"mi/baseline/logout\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-dropdown>\n</body>\n```\n\n#### Styling Customization\n\nCustomize the dropdown only through its documented `--mds-dropdown-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` to preserve dark-mode and high-contrast behavior.\n\n```css\n.my-context mds-dropdown {\n --mds-dropdown-background: rgb(var(--tone-neutral-09));\n --mds-dropdown-drop-shadow-color-rgb: var(--variant-primary-03);\n --mds-dropdown-duration: 0.3s;\n --mds-dropdown-mouseover-delay: 0.2s;\n --mds-dropdown-z-index: 5000;\n}\n```\n",
|
|
7093
|
+
"1. Description": "The `<mds-dropdown>` web component is a floating overlay surface of the Magma Design System that anchors arbitrary slotted content next to an external trigger element. It has no built-in trigger of its own: it attaches to a separate caller resolved via `target` and positions, flips and shifts itself around that element.\n\n#### Semantic Behavior\n\n- **Caller binding**: The dropdown does not render a trigger; it resolves its caller from the `target` selector and wires the chosen interaction onto that external element. Changing `target` re-binds the caller.\n- **Visibility is the single source of truth**: The `visible` prop drives the whole lifecycle - it positions the floating element, optionally shows the backdrop, and emits the events; setting it back to `false` dismisses it.\n- **Outside-click dismissal**: While open, clicking outside both the host and the caller closes the dropdown.\n- **Escape to close**: Pressing Escape hides the dropdown, and hands the focus back to the caller when the panel was holding it.\n- **Keyboard, when the panel is a `menu`**: the arrows on the caller open the panel and land on the first entry (Up on the last), Enter does the same; inside the panel the arrows walk the entries and wrap at the ends, Home and End go to the first and to the last, Tab closes and lets the focus leave from the caller. A panel that declares another role is left alone: the arrows of a calendar or of a form belong to what the panel holds.\n- **Backdrop**: When `backdrop` is set, a backdrop is shown while the dropdown is visible and removed on close.\n- **Emitted events**: `mdsDropdownChange` fires on every visibility transition; `mdsDropdownVisible` and `mdsDropdownHide` fire on open and close respectively. Each detail carries the resolved `caller` and the current `visible` state.\n- **Default slot is the panel content**: Anything in the default slot (text, HTML, or other components) is the surface shown when the dropdown is triggered.\n- **ARIA wiring**: The panel declares itself a `menu` and names the elements the slot receives as its entries (`role=\"menuitem\"`, a role of their own being left alone); the caller receives `aria-haspopup`, an `aria-controls` pointing at the panel and an `aria-expanded` that follows `visible`. A panel that is not a list of actions declares its own `role` in the markup and keeps it, its contents then being left alone. A caller that exposes no role of its own - a generic host that keeps its control inside its shadow root, such as `mds-tab-item` - is left unwired, none of those attributes being valid on it.\n\n#### Properties & Visual Configurations\n\n- **`interaction`** decides how the caller opens the panel: `'click'` toggles on caller click (with outside-click and Escape dismissal), `'mouseover'` opens on hover and closes on mouse leave, and `'none'` disables all automatic wiring so visibility is controlled programmatically through `visible`.\n- **`target`** (required) is the CSS selector of the external element the dropdown attaches to and positions against.\n\n#### Other behavioral props\n\n- **`placement`** sets the preferred side relative to the caller; the best side is chosen automatically by default (**`disableAutoPlacement`** opts out and pins to `placement`), **`flip`** allows falling back to the opposite side when space runs out, and the panel is shifted to stay inside the viewport with a safe margin by default — **`disableShift`** opts out of this and **`shiftPadding`** tunes the margin.\n- **`offset`** controls the gap between the panel and the caller; the pointer toward the caller is shown by default (**`hideArrow`** removes it) and **`arrowPadding`** insets it from the panel edges.\n- the panel tracks the caller smoothly as the page scrolls by default (**`disableSmooth`** opts out); **`strategy`** chooses the CSS positioning mode (`'absolute'` vs `'fixed'`) and **`zIndex`** sets the stacking order.\n",
|
|
7094
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-dropdown>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Dropdown Menu\n\nThe minimal required setup: a trigger element with a unique `id` and a `<mds-dropdown>` with `target` pointing at it. The dropdown binds to the caller on `click` by default and dismisses on outside-click or Escape.\n\n```html\n<mds-button id=\"menu-utente\" label=\"Profilo\" icon=\"mi/baseline/account-circle\" variant=\"secondary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#menu-utente\">\n <mds-button icon=\"mi/baseline/settings\" variant=\"dark\" tone=\"text\" label=\"Impostazioni account\"></mds-button>\n <mds-button icon=\"mi/baseline/logout\" variant=\"error\" tone=\"text\" label=\"Esci\"></mds-button>\n</mds-dropdown>\n```\n\n#### Panel That Is Not a Menu\n\nThe dropdown is a `menu` by default, a list of actions being what it holds most of the time. A panel that holds anything else - a calendar, a form, a paragraph with a link - declares its own `role`, which the component never overwrites: its contents are then left alone instead of being named entries of a menu.\n\n```html\n<mds-button id=\"info-policy\" label=\"Come usiamo i tuoi dati\" variant=\"secondary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#info-policy\" role=\"group\">\n <mds-text typography=\"tip\">I dati restano sui server di Maggioli.</mds-text>\n <mds-button href=\"/policy\" label=\"Leggi la policy\" variant=\"dark\" tone=\"text\" size=\"sm\"></mds-button>\n</mds-dropdown>\n```\n\n#### Dropdown with Arrow Pointer\n\nThe arrow pointer is shown by default to visually connect the panel to its caller; add `hide-arrow` to remove it. Adjust `arrow-padding` when the panel is narrow and the arrow would clip the rounded corners.\n\n```html\n<mds-button id=\"aiuto-contestuale\" label=\"Aiuto\" icon=\"mi/baseline/help-outline\" variant=\"secondary\" tone=\"outline\"></mds-button>\n\n<mds-dropdown target=\"#aiuto-contestuale\" arrow-padding=\"16\">\n <mds-text typography=\"h6\">Come funziona?</mds-text>\n <mds-text typography=\"detail\">Seleziona un campo per vedere la guida contestuale.</mds-text>\n</mds-dropdown>\n```\n\n#### Dropdown with Backdrop\n\nUse `backdrop` to dim the rest of the page while the panel is open. This is appropriate for panels with a higher modal weight, such as user-account menus or multi-step pickers.\n\n```html\n<mds-button id=\"selezione-filtri\" label=\"Filtra risultati\" icon=\"mi/baseline/filter-list\" variant=\"primary\"></mds-button>\n\n<mds-dropdown target=\"#selezione-filtri\" backdrop>\n <mds-text typography=\"h6\">Filtra per categoria</mds-text>\n <mds-filter>\n <mds-filter-item label=\"Documenti\"></mds-filter-item>\n <mds-filter-item label=\"Immagini\"></mds-filter-item>\n <mds-filter-item label=\"Video\"></mds-filter-item>\n </mds-filter>\n</mds-dropdown>\n```\n\n#### Mouseover Interaction\n\nSet `interaction=\"mouseover\"` for navigation mega-menus or info tooltips that should open on hover. The component adds a configurable delay (default 0.5 s, controlled by `--mds-dropdown-mouseover-delay`) before opening and closing.\n\n```html\n<mds-button id=\"info-progetto\" label=\"Dettagli progetto\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-dropdown target=\"#info-progetto\" interaction=\"mouseover\">\n <mds-entity icon=\"mi/baseline/folder\">\n <mds-text>Progetto Alfa - In corso</mds-text>\n </mds-entity>\n</mds-dropdown>\n```\n\n#### Programmatic Control via `visible`\n\nSet `interaction=\"none\"` to disable automatic wiring and drive visibility yourself. This is useful when the trigger logic lives in app code - for example, opening on a keyboard shortcut or a programmatic state change.\n\n```html\n<mds-button id=\"apri-manuale\" label=\"Apri pannello\" variant=\"secondary\"></mds-button>\n\n<mds-dropdown id=\"pannello-opzioni\" target=\"#apri-manuale\" interaction=\"none\">\n <mds-text typography=\"detail\">Pannello gestito dal codice applicativo.</mds-text>\n</mds-dropdown>\n\n<script>\n const dropdown = document.querySelector('#pannello-opzioni');\n document.querySelector('#apri-manuale').addEventListener('click', () => {\n dropdown.visible = !dropdown.visible;\n });\n</script>\n```\n\n#### Placement and Auto-Placement\n\nUse `placement` to anchor the panel to a specific side of the caller. Auto-placement is on by default, letting the component choose the best available side based on viewport space; add `disable-auto-placement` to pin the panel strictly to `placement`.\n\n```html\n<!-- Pinned right-start placement (auto-placement disabled) -->\n<mds-button id=\"azioni-riga\" label=\"Azioni\" icon=\"mi/baseline/more-vert\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-dropdown target=\"#azioni-riga\" placement=\"right-start\" disable-auto-placement>\n <mds-button icon=\"mi/baseline/edit\" variant=\"dark\" tone=\"text\" label=\"Modifica\"></mds-button>\n <mds-button icon=\"mi/baseline/delete\" variant=\"error\" tone=\"text\" label=\"Elimina\"></mds-button>\n</mds-dropdown>\n\n<!-- Auto-placement (default) for constrained viewports -->\n<mds-button id=\"opzioni-voce\" label=\"Opzioni\" variant=\"secondary\" tone=\"weak\"></mds-button>\n<mds-dropdown target=\"#opzioni-voce\">\n <mds-button label=\"Duplica\" icon=\"mi/baseline/content-copy\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-dropdown>\n```\n\n#### Flip and Shift for Viewport Safety\n\nEnable `flip` to let the panel jump to the opposite side when there is not enough space in the preferred direction. Shifting the panel to keep it inside the viewport is on by default; tune the safe margin with `shift-padding` (or set `disable-shift` to opt out).\n\n```html\n<mds-button id=\"btn-edge\" label=\"Vicino al bordo\" variant=\"primary\"></mds-button>\n\n<mds-dropdown target=\"#btn-edge\" placement=\"top\" flip shift-padding=\"16\">\n <mds-text typography=\"detail\">Questo pannello si sposta automaticamente se manca spazio.</mds-text>\n</mds-dropdown>\n```\n\n#### Listening to Visibility Events\n\nListen for `mdsDropdownVisible`, `mdsDropdownHide`, or `mdsDropdownChange` to react to open/close transitions. Each event detail contains `caller` (the resolved trigger element) and `visible` (the new state).\n\n```html\n<mds-button id=\"btn-notifica\" label=\"Notifiche\" icon=\"mi/baseline/notifications\" variant=\"secondary\"></mds-button>\n\n<mds-dropdown id=\"pannello-notifiche\" target=\"#btn-notifica\">\n <mds-text typography=\"detail\">Nessuna nuova notifica.</mds-text>\n</mds-dropdown>\n\n<script>\n document.querySelector('#pannello-notifiche').addEventListener('mdsDropdownVisible', (e) => {\n console.log('Aperto. Trigger:', e.detail.caller);\n });\n document.querySelector('#pannello-notifiche').addEventListener('mdsDropdownHide', () => {\n console.log('Chiuso.');\n });\n</script>\n```\n\n#### Strategy `fixed` Inside Scrolling or Stacked Containers\n\nUse `strategy=\"fixed\"` when the dropdown is placed inside a scroll container, a sticky header, or a modal. With `strategy=\"absolute\"` (the default) the panel may be clipped by `overflow: hidden` ancestors.\n\n```html\n<!-- Inside a modal or a sticky nav - use fixed positioning -->\n<mds-button id=\"menu-header\" label=\"Menu\" variant=\"secondary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#menu-header\" strategy=\"fixed\">\n <mds-button label=\"Pagina principale\" icon=\"mi/baseline/home\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Impostazioni\" icon=\"mi/baseline/settings\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-dropdown>\n```\n\n#### DOM Placement at the Document Root\n\nPlace `<mds-dropdown>` as a direct child of `<body>` (or as close as possible to the root) when the caller lives deep inside a stacking context. Nesting the dropdown inside the same transformed or `overflow: hidden` ancestor as the caller can break positioning and backdrop rendering.\n\n```html\n<body>\n <!-- Trigger lives inside a complex layout -->\n <div class=\"app-layout\">\n <nav>\n <mds-button id=\"btn-profilo\" label=\"Profilo\" variant=\"secondary\"></mds-button>\n </nav>\n </div>\n\n <!-- Dropdown is a sibling of the layout root, not nested inside it -->\n <mds-dropdown target=\"#btn-profilo\" strategy=\"fixed\" backdrop>\n <mds-text typography=\"h6\">Mario Rossi</mds-text>\n <mds-button label=\"Esci\" icon=\"mi/baseline/logout\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-dropdown>\n</body>\n```\n\n#### Styling Customization\n\nCustomize the dropdown only through its documented `--mds-dropdown-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` to preserve dark-mode and high-contrast behavior.\n\n```css\n.my-context mds-dropdown {\n --mds-dropdown-background: rgb(var(--tone-neutral-09));\n --mds-dropdown-drop-shadow-color-rgb: var(--variant-primary-03);\n --mds-dropdown-duration: 0.3s;\n --mds-dropdown-mouseover-delay: 0.2s;\n --mds-dropdown-z-index: 5000;\n}\n```\n",
|
|
7172
7095
|
"3. Antipattern": "Common incorrect uses of `<mds-dropdown>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Place the Dropdown Deep Inside a Scroll or Stacking Context\n\nNesting `<mds-dropdown>` inside a transformed, sticky, or `overflow: hidden` ancestor breaks floating positioning and backdrop rendering. Place it as close to `<body>` as the page structure allows, or switch to `strategy=\"fixed\"`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<div style=\"overflow: hidden; position: relative;\">\n <mds-button id=\"trigger\" label=\"Apri\" variant=\"primary\"></mds-button>\n <mds-dropdown target=\"#trigger\" backdrop>\n <mds-text>Contenuto</mds-text>\n </mds-dropdown>\n</div>\n\n<!-- ✅ CORRECT -->\n<div style=\"overflow: hidden; position: relative;\">\n <mds-button id=\"trigger\" label=\"Apri\" variant=\"primary\"></mds-button>\n</div>\n<mds-dropdown target=\"#trigger\" strategy=\"fixed\" backdrop>\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n```\n\n#### Do Not Use `visible=\"false\"` to Close the Dropdown\n\n`visible` is a boolean prop. Setting it to the string `\"false\"` is truthy in HTML - the dropdown stays open. Remove the attribute or set the property to `false` in JavaScript to close it.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-dropdown target=\"#btn\" visible=\"false\">\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n\n<!-- ✅ CORRECT -->\n<mds-dropdown target=\"#btn\">\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n```\n\n```js\n// ✅ CORRECT - closing programmatically\ndocument.querySelector('mds-dropdown').visible = false;\n```\n\n#### Do Not Listen for Native `click` on the Target Instead of Dropdown Events\n\nThe dropdown manages its own interaction and emits `mdsDropdownVisible`, `mdsDropdownHide`, and `mdsDropdownChange`. Attaching a raw `click` listener to the caller can interfere with inside-click handling and may fire before the dropdown has updated its state.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-button id=\"btn-info\" label=\"Info\" variant=\"secondary\"></mds-button>\n<mds-dropdown target=\"#btn-info\">...</mds-dropdown>\n\n<script>\n // raw native event on the caller - races with dropdown internals\n document.querySelector('#btn-info').addEventListener('click', () => {\n console.log('cliccato');\n });\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-button id=\"btn-info\" label=\"Info\" variant=\"secondary\"></mds-button>\n<mds-dropdown id=\"dd-info\" target=\"#btn-info\">...</mds-dropdown>\n\n<script>\n document.querySelector('#dd-info').addEventListener('mdsDropdownVisible', (e) => {\n console.log('dropdown aperto', e.detail.visible);\n });\n</script>\n```\n\n#### Do Not Use `target` Without a Matching Element in the DOM\n\n`target` is resolved with `querySelector` at `componentDidLoad` time. If the selector does not match any element the dropdown has no caller and cannot position or open itself. Always verify the `id` is present in the DOM before the component loads.\n\n```html\n<!-- 🚫 INCORRECT - typo: button has id \"btn-salva\", target points to \"#salva\" -->\n<mds-button id=\"btn-salva\" label=\"Salva\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#salva\">\n <mds-text>Opzioni di salvataggio</mds-text>\n</mds-dropdown>\n\n<!-- ✅ CORRECT -->\n<mds-button id=\"btn-salva\" label=\"Salva\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#btn-salva\">\n <mds-text>Opzioni di salvataggio</mds-text>\n</mds-dropdown>\n```\n\n#### Do Not Use `<mds-button-dropdown>` and `<mds-dropdown>` Interchangeably\n\n[`mds-button-dropdown`](../../mds-button-dropdown) is a compound component that already embeds a trigger button and a dropdown. Use it for a simple action-button-plus-menu. Use `<mds-dropdown>` directly only when the caller is not an `mds-button`, or when you need full control over the trigger element.\n\n```html\n<!-- 🚫 INCORRECT - re-implementing what mds-button-dropdown already does -->\n<mds-button id=\"btn-azioni\" label=\"Azioni\" icon=\"mi/baseline/expand-more\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#btn-azioni\">\n <mds-button label=\"Modifica\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-dropdown>\n\n<!-- ✅ CORRECT - use the dedicated compound component -->\n<mds-button-dropdown label=\"Azioni\" variant=\"primary\">\n <mds-button label=\"Modifica\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Customize via Undocumented Shadow Internals\n\nThe supported customization surface is the `--mds-dropdown-*` CSS custom properties. Targeting internal elements via `::part()` on non-documented parts, `>>>`, or class-name selectors couples your code to the Shadow DOM structure and breaks on any internal refactor.\n\n```css\n/* 🚫 INCORRECT */\nmds-dropdown::part(panel) {\n border: 2px solid red;\n}\nmds-dropdown >>> .arrow {\n display: none;\n}\n\n/* ✅ CORRECT */\nmds-dropdown {\n --mds-dropdown-background: rgb(var(--tone-neutral-08));\n --mds-dropdown-z-index: 6000;\n}\n```\n"
|
|
7173
7096
|
},
|
|
7174
7097
|
"props": [
|
|
@@ -7758,7 +7681,7 @@
|
|
|
7758
7681
|
"docs": "Sets the transition duration of the backdrop, used by component's code too."
|
|
7759
7682
|
},
|
|
7760
7683
|
{
|
|
7761
|
-
"name": "--mds-dropdown-backdrop-z-
|
|
7684
|
+
"name": "--mds-dropdown-backdrop-z-index",
|
|
7762
7685
|
"annotation": "prop",
|
|
7763
7686
|
"docs": "Sets the backdrop z-index, used by component's code too."
|
|
7764
7687
|
},
|
|
@@ -7822,7 +7745,7 @@
|
|
|
7822
7745
|
"mds-input-date-range",
|
|
7823
7746
|
"mds-policy-ai",
|
|
7824
7747
|
"mds-pref-language",
|
|
7825
|
-
"mds-pref-theme
|
|
7748
|
+
"mds-pref-theme"
|
|
7826
7749
|
],
|
|
7827
7750
|
"dependencies": [],
|
|
7828
7751
|
"dependencyGraph": {
|
|
@@ -7841,7 +7764,7 @@
|
|
|
7841
7764
|
"mds-pref-language": [
|
|
7842
7765
|
"mds-dropdown"
|
|
7843
7766
|
],
|
|
7844
|
-
"mds-pref-theme
|
|
7767
|
+
"mds-pref-theme": [
|
|
7845
7768
|
"mds-dropdown"
|
|
7846
7769
|
]
|
|
7847
7770
|
}
|
|
@@ -7855,7 +7778,7 @@
|
|
|
7855
7778
|
"docsTags": [],
|
|
7856
7779
|
"usage": {
|
|
7857
7780
|
"1. Description": "The `<mds-emoji>` web component renders one of the Magma Design System's animated mascot illustrations (`mia` or `simi`) as an interactive SVG. It is a decorative, expressive element with no native HTML equivalent: its personality is driven entirely through imperative animation methods rather than markup or props.\n\n#### Semantic Behavior\n\n- **Mouse following**: When started, the emoji tracks the pointer with a 3D head rotation and parallax on each facial part; it is off by default and only reacts after `startFollowMouse()` is called.\n- **Single-animation lock**: Expressive actions are serialized - `agree`, `smile`, `disagree`, and `startThinking` no-op while another animation is running, so triggers cannot overlap or interrupt each other.\n- **Promise-based methods**: Every expressive action returns a `Promise<void>` that resolves when its animation finishes, letting callers await one expression before chaining the next.\n- **State restoration**: When an animation completes, any mouse-following that was active beforehand is automatically restored.\n- **Idle blinking**: `startBlinking()` runs a random blink loop on the eyes; blinks are suppressed while the emoji is busy with another animation.\n\n#### Properties & Visual Configurations\n\nThe only public prop is `name`, which selects the mascot identity. It accepts `'mia'` (the default) or `'simi'`; changing it at runtime swaps the mascot.\n\n#### Other behavioral props\n\nThere are no variant, tone, or size props. The expression is configured imperatively through method calls (`agree`, `smile`, `disagree`, `startThinking` / `stopThinking`, `startBlinking` / `stopBlinking`, `startFollowMouse` / `stopFollowMouse`), and the timing and reach of those animations are tuned through CSS custom properties - `--mds-emoji-expression-max-rotation`, the `--mds-emoji-expression-follow-mouse-*-duration` pair, the per-part `--mds-emoji-offset-*` values, and the per-mascot color tokens - rather than through attributes.\n",
|
|
7858
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-emoji>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md) and the component catalogue in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md).\n\n#### Basic Mascot Display\n\nDrop the component anywhere to render the default mascot, Mia. The element is a square and sizes itself to the value applied via CSS `width` / `height` (it has its own default). No props are required for a static illustration.\n\n```html\n<mds-emoji></mds-emoji>\n```\n\n#### Choosing a Mascot with `name`\n\nThe `name` prop selects between the two available mascots. Use `\"mia\"` (default) for the AI-branded identity and `\"simi\"` for the human-like character. Changing `name` at runtime swaps the mascot without a page reload.\n\n```html\n<!-- Mia - the AI mascot (default) -->\n<mds-emoji name=\"mia\"></mds-emoji>\n\n<!-- Simi - the human-like mascot -->\n<mds-emoji name=\"simi\"></mds-emoji>\n```\n\n#### Sizing via CSS\n\nControl the rendered size with CSS `width` and `height` on the host - the SVG fills 100% of the host's box. The component keeps a 1:1 aspect ratio automatically.\n\n```html\n<mds-emoji name=\"mia\" style=\"width: 128px; height: 128px;\"></mds-emoji>\n```\n\n```css\n.mascot-hero mds-emoji {\n width: 240px;\n height: 240px;\n}\n```\n\n#### Mouse-Following Interaction\n\nCall `startFollowMouse()` to activate the 3D head-rotation that tracks the pointer. The feature is off by default. Call `stopFollowMouse()` to deactivate it cleanly.\n\n```html\n<mds-emoji id=\"mascot\" name=\"mia\"></mds-emoji>\n\n<script>\n const emoji = document.querySelector('#mascot');\n emoji.startFollowMouse();\n\n // later, e.g. when leaving a focused section:\n emoji.stopFollowMouse();\n</script>\n```\n\n#### Idle Blinking\n\nStart the automatic random-interval blink loop with `startBlinking()`. The blink is suppressed while another animation owns the eyes and resumes automatically afterwards.\n\n```html\n<mds-emoji id=\"mascot\" name=\"simi\"></mds-emoji>\n\n<script>\n const emoji = document.querySelector('#mascot');\n emoji.startBlinking();\n</script>\n```\n\n#### Expressing Agreement or Confirmation\n\nCall `agree()` after a successful form submission or confirmed action. The emoji nods and briefly smiles. The returned `Promise` resolves when the animation completes.\n\n```html\n<mds-emoji id=\"mascot\" name=\"mia\"></mds-emoji>\n<mds-button id=\"save-btn\" label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n\n<script>\n const emoji = document.querySelector('#mascot');\n document.querySelector('#save-btn').addEventListener('click', async () => {\n await fetch('/api/save');\n emoji.agree();\n });\n</script>\n```\n\n#### Expressing a Smile\n\nCall `smile()` for lighter positive feedback - a bounce and closed-eyes smile without the full nod. Useful on hover or focus of a featured element.\n\n```html\n<mds-emoji id=\"mascot\" name=\"mia\"></mds-emoji>\n\n<script>\n const emoji = document.querySelector('#mascot');\n document.querySelector('.feature-card').addEventListener('mouseenter', () => {\n emoji.smile();\n });\n</script>\n```\n\n#### Expressing Disagreement or Errors\n\nCall `disagree()` on validation failure or destructive confirmation. An optional `turnHappyDelay` number (in milliseconds) delays the return to the neutral face - useful when you want the serious expression to linger while an error message is visible.\n\n```html\n<mds-emoji id=\"mascot\" name=\"mia\"></mds-emoji>\n\n<script>\n const emoji = document.querySelector('#mascot');\n\n formEl.addEventListener('submit', async (e) => {\n e.preventDefault();\n const ok = await submitForm();\n if (!ok) {\n emoji.disagree(2000); // stay serious for 2 s while the error banner is visible\n }\n });\n</script>\n```\n\n#### Thinking State During Async Operations\n\nCall `startThinking()` while a request is in flight - the emoji raises a thinking hand and shifts its gaze. Call `stopThinking()` when the operation settles. Both methods accept an optional `duration` (seconds) for the transition animation.\n\n```html\n<mds-emoji id=\"mascot\" name=\"mia\"></mds-emoji>\n\n<script>\n const emoji = document.querySelector('#mascot');\n\n async function caricaDati() {\n await emoji.startThinking();\n const data = await fetch('/api/data').then((r) => r.json());\n await emoji.stopThinking();\n return data;\n }\n</script>\n```\n\n#### Chaining Expressions\n\nBecause every method returns a `Promise<void>`, you can `await` one before triggering the next. The single-animation lock ensures they never overlap even if called without awaiting.\n\n```html\n<mds-emoji id=\"mascot\" name=\"simi\"></mds-emoji>\n\n<script>\n const emoji = document.querySelector('#mascot');\n\n async function onSave() {\n await emoji.startThinking(0.4); // mostri caricamento\n await fetch('/api/salva');\n await emoji.stopThinking(0.4);\n await emoji.agree(); // conferma riuscita\n }\n</script>\n```\n\n#### CSS Customization - Animation Timing\n\nTune the mouse-follow responsiveness by overriding the documented `--mds-emoji-expression-*` custom properties on the host or a parent selector. The initial values are reasonable for most placements; reduce them for snappier feedback.\n\n```css\n.mascot-container mds-emoji {\n --mds-emoji-expression-follow-mouse-head-duration: 150ms;\n --mds-emoji-expression-follow-mouse-traits-duration: 100ms;\n --mds-emoji-expression-max-rotation: 10deg;\n}\n```\n\n#### CSS Customization - Mascot Colors\n\nOverride per-mascot color tokens to adapt the character to a custom brand palette. Use Magma token wrappers (`rgb(var(--...))`) so dark-mode and high-contrast adaptations keep working.\n\n```css\n/* Theming Mia for a custom brand */\nmds-emoji[name='mia'] {\n --mds-emoji-mia-head: rgb(var(--variant-primary-08));\n --mds-emoji-mia-eyes: rgb(var(--variant-primary-03));\n --mds-emoji-mia-mouth: rgb(var(--variant-primary-06));\n --mds-emoji-mia-hands: rgb(var(--variant-primary-06));\n}\n\n/* Theming Simi */\nmds-emoji[name='simi'] {\n --mds-emoji-simi-skin: #f5c8a0;\n --mds-emoji-simi-skin-dark: #c8895e;\n --mds-emoji-simi-skin-light: #fdebd8;\n}\n```\n\n#### CSS Customization - Parallax Offsets\n\nIncrease or decrease the per-layer offset values to control how pronounced the parallax depth effect is when the emoji follows the mouse. Set all offsets to `0` to flatten the effect entirely.\n\n```css\n/* Subtle parallax - small offsets for compact placements */\n.compact mds-emoji {\n --mds-emoji-offset-eyes: 0.5px;\n --mds-emoji-offset-mouth: 0.5px;\n --mds-emoji-offset-eyebrows: 4px;\n --mds-emoji-offset-head: 0;\n}\n\n/* Dramatic parallax - large offsets for hero sections */\n.hero mds-emoji {\n --mds-emoji-offset-eyes: 3px;\n --mds-emoji-offset-mouth: 3px;\n --mds-emoji-offset-eyebrows: 20px;\n --mds-emoji-perspective: 250px;\n}\n```\n",
|
|
7781
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-emoji>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md) and the component catalogue in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md).\n\n#### Basic Mascot Display\n\nDrop the component anywhere to render the default mascot, Mia. The element is a square and sizes itself to the value applied via CSS `width` / `height` (it has its own default). No props are required for a static illustration.\n\n```html\n<mds-emoji></mds-emoji>\n```\n\n#### Choosing a Mascot with `name`\n\nThe `name` prop selects between the two available mascots. Use `\"mia\"` (default) for the AI-branded identity and `\"simi\"` for the human-like character. Changing `name` at runtime swaps the mascot without a page reload.\n\n```html\n<!-- Mia - the AI mascot (default) -->\n<mds-emoji name=\"mia\"></mds-emoji>\n\n<!-- Simi - the human-like mascot -->\n<mds-emoji name=\"simi\"></mds-emoji>\n```\n\n#### Sizing via CSS\n\nControl the rendered size with CSS `width` and `height` on the host - the SVG fills 100% of the host's box. The component keeps a 1:1 aspect ratio automatically.\n\n```html\n<mds-emoji name=\"mia\" style=\"width: 128px; height: 128px;\"></mds-emoji>\n```\n\n```css\n.mascot-hero mds-emoji {\n width: 240px;\n height: 240px;\n}\n```\n\n#### Mouse-Following Interaction\n\nCall `startFollowMouse()` to activate the 3D head-rotation that tracks the pointer. The feature is off by default. Call `stopFollowMouse()` to deactivate it cleanly.\n\n```html\n<mds-emoji id=\"mascot\" name=\"mia\"></mds-emoji>\n\n<script>\n const emoji = document.querySelector('#mascot');\n emoji.startFollowMouse();\n\n // later, e.g. when leaving a focused section:\n emoji.stopFollowMouse();\n</script>\n```\n\n#### Idle Blinking\n\nStart the automatic random-interval blink loop with `startBlinking()`. The blink is suppressed while another animation owns the eyes and resumes automatically afterwards.\n\n```html\n<mds-emoji id=\"mascot\" name=\"simi\"></mds-emoji>\n\n<script>\n const emoji = document.querySelector('#mascot');\n emoji.startBlinking();\n</script>\n```\n\n#### Expressing Agreement or Confirmation\n\nCall `agree()` after a successful form submission or confirmed action. The emoji nods and briefly smiles. The returned `Promise` resolves when the animation completes.\n\n```html\n<mds-emoji id=\"mascot\" name=\"mia\"></mds-emoji>\n<mds-button id=\"save-btn\" label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n\n<script>\n const emoji = document.querySelector('#mascot');\n document.querySelector('#save-btn').addEventListener('click', async () => {\n await fetch('/api/save');\n emoji.agree();\n });\n</script>\n```\n\n#### Expressing a Smile\n\nCall `smile()` for lighter positive feedback - a bounce and closed-eyes smile without the full nod. Useful on hover or focus of a featured element.\n\n```html\n<mds-emoji id=\"mascot\" name=\"mia\"></mds-emoji>\n\n<script>\n const emoji = document.querySelector('#mascot');\n document.querySelector('.feature-card').addEventListener('mouseenter', () => {\n emoji.smile();\n });\n</script>\n```\n\n#### Expressing Disagreement or Errors\n\nCall `disagree()` on validation failure or destructive confirmation. An optional `turnHappyDelay` number (in milliseconds) delays the return to the neutral face - useful when you want the serious expression to linger while an error message is visible.\n\n```html\n<mds-emoji id=\"mascot\" name=\"mia\"></mds-emoji>\n\n<script>\n const emoji = document.querySelector('#mascot');\n\n formEl.addEventListener('submit', async (e) => {\n e.preventDefault();\n const ok = await submitForm();\n if (!ok) {\n emoji.disagree(2000); // stay serious for 2 s while the error banner is visible\n }\n });\n</script>\n```\n\n#### Thinking State During Async Operations\n\nCall `startThinking()` while a request is in flight - the emoji raises a thinking hand and shifts its gaze. Call `stopThinking()` when the operation settles. Both methods accept an optional `duration` (seconds) for the transition animation.\n\n```html\n<mds-emoji id=\"mascot\" name=\"mia\"></mds-emoji>\n\n<script>\n const emoji = document.querySelector('#mascot');\n\n async function caricaDati() {\n await emoji.startThinking();\n const data = await fetch('/api/data').then((r) => r.json());\n await emoji.stopThinking();\n return data;\n }\n</script>\n```\n\n#### Chaining Expressions\n\nBecause every method returns a `Promise<void>`, you can `await` one before triggering the next. The single-animation lock ensures they never overlap even if called without awaiting.\n\n```html\n<mds-emoji id=\"mascot\" name=\"simi\"></mds-emoji>\n\n<script>\n const emoji = document.querySelector('#mascot');\n\n async function onSave() {\n await emoji.startThinking(0.4); // mostri caricamento\n await fetch('/api/salva');\n await emoji.stopThinking(0.4);\n await emoji.agree(); // conferma riuscita\n }\n</script>\n```\n\n#### CSS Customization - Animation Timing\n\nTune the mouse-follow responsiveness by overriding the documented `--mds-emoji-expression-*` custom properties on the host or a parent selector. The initial values are reasonable for most placements; reduce them for snappier feedback.\n\n```css\n.mascot-container mds-emoji {\n --mds-emoji-expression-follow-mouse-head-duration: 150ms;\n --mds-emoji-expression-follow-mouse-traits-duration: 100ms;\n --mds-emoji-expression-max-rotation: 10deg;\n}\n```\n\n#### CSS Customization - Mascot Colors\n\nOverride per-mascot color tokens to adapt the character to a custom brand palette. Use Magma token wrappers (`rgb(var(--...))`) so dark-mode and high-contrast adaptations keep working.\n\n```css\n/* Theming Mia for a custom brand */\nmds-emoji[name='mia'] {\n --mds-emoji-mia-head-color: rgb(var(--variant-primary-08));\n --mds-emoji-mia-eyes-color: rgb(var(--variant-primary-03));\n --mds-emoji-mia-mouth-color: rgb(var(--variant-primary-06));\n --mds-emoji-mia-hands-color: rgb(var(--variant-primary-06));\n}\n\n/* Theming Simi */\nmds-emoji[name='simi'] {\n --mds-emoji-simi-skin: #f5c8a0;\n --mds-emoji-simi-skin-dark: #c8895e;\n --mds-emoji-simi-skin-light: #fdebd8;\n}\n```\n\n#### CSS Customization - Parallax Offsets\n\nIncrease or decrease the per-layer offset values to control how pronounced the parallax depth effect is when the emoji follows the mouse. Set all offsets to `0` to flatten the effect entirely.\n\n```css\n/* Subtle parallax - small offsets for compact placements */\n.compact mds-emoji {\n --mds-emoji-offset-eyes: 0.5px;\n --mds-emoji-offset-mouth: 0.5px;\n --mds-emoji-offset-eyebrows: 4px;\n --mds-emoji-offset-head: 0;\n}\n\n/* Dramatic parallax - large offsets for hero sections */\n.hero mds-emoji {\n --mds-emoji-offset-eyes: 3px;\n --mds-emoji-offset-mouth: 3px;\n --mds-emoji-offset-eyebrows: 20px;\n --mds-emoji-perspective: 250px;\n}\n```\n",
|
|
7859
7782
|
"3. Antipattern": "Common incorrect uses of `<mds-emoji>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use an Unknown `name` Value\n\nOnly `\"mia\"` and `\"simi\"` are valid values for the `name` prop. Any other string falls outside the `EmojiNames` type, produces no mascot, and silently renders nothing.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-emoji name=\"luigi\"></mds-emoji>\n<mds-emoji name=\"robot\"></mds-emoji>\n\n<!-- ✅ CORRECT -->\n<mds-emoji name=\"mia\"></mds-emoji>\n<mds-emoji name=\"simi\"></mds-emoji>\n```\n\n#### Do Not Put Content in the Component - It Has No Slots\n\n`<mds-emoji>` renders a self-contained SVG through its shadow root and exposes no slots. Any child nodes placed between the tags are ignored entirely.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-emoji name=\"mia\">\n <span>Ciao!</span>\n</mds-emoji>\n\n<!-- ✅ CORRECT - place sibling elements outside the component -->\n<div class=\"mascot-wrapper\">\n <mds-emoji name=\"mia\"></mds-emoji>\n <p>Ciao!</p>\n</div>\n```\n\n#### Do Not Trigger Expressions Without Awaiting a Running Animation\n\nThe single-animation lock causes `agree()`, `smile()`, `disagree()`, and `startThinking()` to no-op when the emoji is already busy. Firing them without awaiting the previous call means subsequent expressions are silently dropped.\n\n```html\n<!-- 🚫 INCORRECT - second call is dropped because the first is still running -->\n<script>\n emoji.startThinking(); // starts thinking\n emoji.agree(); // no-op: emoji is busy\n</script>\n\n<!-- ✅ CORRECT - await each expression before chaining the next -->\n<script>\n await emoji.startThinking(0.5);\n await fetch('/api/salva');\n await emoji.stopThinking(0.5);\n await emoji.agree();\n</script>\n```\n\n#### Do Not Use `stopThinking()` to Cancel Mid-Expression\n\n`stopThinking()` is the paired counterpart to `startThinking()`. Calling it to interrupt `agree()`, `smile()`, or `disagree()` has no effect because those animations set their own completion callbacks and do not check the thinking state.\n\n```html\n<!-- 🚫 INCORRECT - stopThinking() won't cut short an agree() animation -->\n<script>\n emoji.agree();\n emoji.stopThinking(); // no-op\n</script>\n\n<!-- ✅ CORRECT - let the animation complete (await it), or accept that expressions run to completion -->\n<script>\n await emoji.agree();\n // now the emoji is idle and ready for the next call\n</script>\n```\n\n#### Do Not Pierce Shadow DOM to Animate SVG Parts Directly\n\nThe internal SVG elements (eyes, mouth, head, etc.) are part of the shadow DOM and are managed by GSAP inside the component. Querying them from outside and applying CSS transforms or animations creates conflicting tweens and breaks the component's state machine.\n\n```css\n/* 🚫 INCORRECT */\nmds-emoji >>> #eyes-default {\n transform: scaleY(0.5);\n}\n```\n\n```html\n<!-- ✅ CORRECT - use the documented imperative methods instead -->\n<script>\n emoji.startBlinking(); // let the component own eye animations\n</script>\n```\n\n#### Do Not Set Per-Layer Offsets with Unitless Numbers\n\nThe `--mds-emoji-offset-*` custom properties are declared as `<length>` values. Unitless numbers are not valid lengths and will be ignored, leaving the parallax effect at the CSS `@property` initial value.\n\n```css\n/* 🚫 INCORRECT - unitless values are invalid <length> */\nmds-emoji {\n --mds-emoji-offset-eyes: 3;\n --mds-emoji-offset-mouth: 2;\n}\n\n/* ✅ CORRECT - always supply a length unit */\nmds-emoji {\n --mds-emoji-offset-eyes: 3px;\n --mds-emoji-offset-mouth: 2px;\n}\n```\n\n#### Do Not Set `--mds-emoji-expression-max-rotation` Without an Angle Unit\n\n`--mds-emoji-expression-max-rotation` is declared as `<angle>`. A bare number is invalid and the property falls back to the initial value of `16deg`, so the constraint you intended is silently ignored.\n\n```css\n/* 🚫 INCORRECT */\nmds-emoji {\n --mds-emoji-expression-max-rotation: 8;\n}\n\n/* ✅ CORRECT */\nmds-emoji {\n --mds-emoji-expression-max-rotation: 8deg;\n}\n```\n"
|
|
7860
7783
|
},
|
|
7861
7784
|
"props": [
|
|
@@ -8201,22 +8124,32 @@
|
|
|
8201
8124
|
"docs": "Sets the maximum rotation angle for the emoji expression"
|
|
8202
8125
|
},
|
|
8203
8126
|
{
|
|
8204
|
-
"name": "--mds-emoji-mia-eyes",
|
|
8127
|
+
"name": "--mds-emoji-mia-eyes-color",
|
|
8205
8128
|
"annotation": "prop",
|
|
8206
8129
|
"docs": "Sets the color of Mia's eyes"
|
|
8207
8130
|
},
|
|
8208
8131
|
{
|
|
8209
|
-
"name": "--mds-emoji-mia-hands",
|
|
8132
|
+
"name": "--mds-emoji-mia-hands-color",
|
|
8210
8133
|
"annotation": "prop",
|
|
8211
8134
|
"docs": "Sets the color of Mia's hands"
|
|
8212
8135
|
},
|
|
8213
8136
|
{
|
|
8214
|
-
"name": "--mds-emoji-mia-head",
|
|
8137
|
+
"name": "--mds-emoji-mia-head-color",
|
|
8215
8138
|
"annotation": "prop",
|
|
8216
8139
|
"docs": "Sets the color of Mia's head"
|
|
8217
8140
|
},
|
|
8218
8141
|
{
|
|
8219
|
-
"name": "--mds-emoji-mia-
|
|
8142
|
+
"name": "--mds-emoji-mia-head-stroke-color",
|
|
8143
|
+
"annotation": "prop",
|
|
8144
|
+
"docs": "Sets the stroke color of Mia's head"
|
|
8145
|
+
},
|
|
8146
|
+
{
|
|
8147
|
+
"name": "--mds-emoji-mia-head-stroke-width",
|
|
8148
|
+
"annotation": "prop",
|
|
8149
|
+
"docs": "Sets the stroke width of Mia's head"
|
|
8150
|
+
},
|
|
8151
|
+
{
|
|
8152
|
+
"name": "--mds-emoji-mia-mouth-color",
|
|
8220
8153
|
"annotation": "prop",
|
|
8221
8154
|
"docs": "Sets the color of Mia's mouth"
|
|
8222
8155
|
},
|
|
@@ -8240,11 +8173,6 @@
|
|
|
8240
8173
|
"annotation": "prop",
|
|
8241
8174
|
"docs": "Sets the positional offset for gadgets"
|
|
8242
8175
|
},
|
|
8243
|
-
{
|
|
8244
|
-
"name": "--mds-emoji-offset-hand",
|
|
8245
|
-
"annotation": "prop",
|
|
8246
|
-
"docs": "Sets the positional offset for the hands"
|
|
8247
|
-
},
|
|
8248
8176
|
{
|
|
8249
8177
|
"name": "--mds-emoji-offset-hands",
|
|
8250
8178
|
"annotation": "prop",
|
|
@@ -8290,6 +8218,16 @@
|
|
|
8290
8218
|
"annotation": "prop",
|
|
8291
8219
|
"docs": "Sets the color of Simi's mouth"
|
|
8292
8220
|
},
|
|
8221
|
+
{
|
|
8222
|
+
"name": "--mds-emoji-simi-mouth-teeth",
|
|
8223
|
+
"annotation": "prop",
|
|
8224
|
+
"docs": "Sets the color of Simi's teeth"
|
|
8225
|
+
},
|
|
8226
|
+
{
|
|
8227
|
+
"name": "--mds-emoji-simi-mouth-throat",
|
|
8228
|
+
"annotation": "prop",
|
|
8229
|
+
"docs": "Sets the color of Simi's throat"
|
|
8230
|
+
},
|
|
8293
8231
|
{
|
|
8294
8232
|
"name": "--mds-emoji-simi-nose",
|
|
8295
8233
|
"annotation": "prop",
|
|
@@ -8357,7 +8295,7 @@
|
|
|
8357
8295
|
}
|
|
8358
8296
|
],
|
|
8359
8297
|
"usage": {
|
|
8360
|
-
"1. Description": "The `<mds-entity>` web component represents a person, organization, or resource as a compact identity block in the Magma Design System, pairing an avatar with a name, optional secondary details, and contextual actions. It has no native HTML equivalent; it standardises how entities are surfaced in lists, headers, and cards.\n\n#### Semantic Behavior\n\n- **Avatar resolution**: The leading avatar renders only when one of `src`, `icon`, or `initials` is provided, following avatar priority (image, then icon, then initials).\n- **Await state**: While `await` is set the avatar is suppressed and a spinner is shown in its place, signalling that the entity is still loading.\n- **Conditional regions**: The `detail` and `action` regions are
|
|
8298
|
+
"1. Description": "The `<mds-entity>` web component represents a person, organization, or resource as a compact identity block in the Magma Design System, pairing an avatar with a name, optional secondary details, and contextual actions. It has no native HTML equivalent; it standardises how entities are surfaced in lists, headers, and cards.\n\n#### Semantic Behavior\n\n- **Avatar resolution**: The leading avatar renders only when one of `src`, `icon`, or `initials` is provided, following avatar priority (image, then icon, then initials).\n- **Await state**: While `await` is set the avatar is suppressed and a spinner is shown in its place, signalling that the entity is still loading.\n- **Conditional regions**: The `detail` and `action` regions are shown only while content is projected into those slots, also when it is added after the first render.\n- **Default slot is the name**: The default slot carries the entity's primary label (text, HTML, or components) and is always rendered inside the info column.\n\n#### Properties & Visual Configurations\n\n- **`src`** is the path to an entity image; **`icon`** is a Magma icon library slug used when no image is supplied; **`initials`** is the text fallback shown when neither image nor icon is set. Provide whichever best identifies the entity - they are mutually prioritised, not combined.\n- **`await`** marks the entity as loading and takes visual precedence over any avatar source.\n\nThe shared `tone` / `variant` ladders are defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system) and color the inner avatar. `tone` is limited to the minimal `'strong'` / `'weak'` pair, and `variant` accepts the avatar colour set; pick them to colour the avatar chip in line with the entity's category.\n\n#### Slots\n\n- **`detail`** holds secondary information (role, email, status) rendered beneath the name.\n- **`action`** holds trailing controls; `mds-button` is the recommended element here.\n",
|
|
8361
8299
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-entity>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Person Entity with Image\n\nThe most common form. Supply `src` for the avatar image and put the entity name in the default slot. Use `<mds-text>` with `typography=\"h6\"` for the primary label so typography tokens are applied consistently.\n\n```html\n<mds-entity src=\"/avatars/mario-rossi.png\">\n <mds-text truncate=\"word\" typography=\"h6\">Mario Rossi</mds-text>\n</mds-entity>\n```\n\n#### Entity with Initials Fallback\n\nWhen no image is available, provide `initials` instead of `src`. The avatar chip renders the initials text.\n\n```html\n<mds-entity initials=\"mr\">\n <mds-text truncate=\"word\" typography=\"h6\">Mario Rossi</mds-text>\n</mds-entity>\n```\n\n#### Entity with Icon\n\nUse `icon` for non-person entities (locations, files, organizations). Reference icons by their slug from the Magma icon library.\n\n```html\n<mds-entity icon=\"mi/baseline/location-on\">\n <mds-text truncate=\"word\" typography=\"h6\">Maggioli Headquarters</mds-text>\n</mds-entity>\n```\n\n#### Secondary Details via `detail` Slot\n\nProject additional information (role, email, status) into the `detail` slot. It renders below the primary name in a subdued color. Use `<mds-text typography=\"caption\">` for plain text details.\n\n```html\n<mds-entity src=\"/avatars/giulia-bianchi.png\">\n <mds-text truncate=\"word\" typography=\"h6\">Giulia Bianchi</mds-text>\n <mds-text truncate=\"word\" slot=\"detail\" typography=\"caption\">giulia@example.com</mds-text>\n <mds-badge slot=\"detail\" variant=\"success\" tone=\"weak\">Attiva</mds-badge>\n</mds-entity>\n```\n\n#### Trailing Action Buttons via `action` Slot\n\nUse the `action` slot for icon-only `<mds-button>` elements. Each button is sized and spaced automatically by the component. Always provide `title` on icon-only buttons for accessibility.\n\n```html\n<mds-entity src=\"/avatars/luca-verdi.png\">\n <mds-text truncate=\"word\" typography=\"h6\">Luca Verdi</mds-text>\n <mds-text truncate=\"word\" slot=\"detail\" typography=\"caption\">luca@example.com</mds-text>\n <mds-button slot=\"action\" icon=\"mdi/pencil\" variant=\"primary\" tone=\"strong\" title=\"Modifica\"></mds-button>\n <mds-button slot=\"action\" icon=\"mdi/delete\" variant=\"error\" tone=\"strong\" title=\"Elimina\"></mds-button>\n</mds-entity>\n```\n\n#### Colored Avatar with `variant` and `tone`\n\nPair `variant` and `tone` to color the avatar chip by entity category. `tone` is limited to `strong` and `weak`; `variant` accepts the full avatar color set.\n\n```html\n<!-- Strong fill, primary variant -->\n<mds-entity icon=\"mi/baseline/business\" variant=\"primary\" tone=\"strong\">\n <mds-text truncate=\"word\" typography=\"h6\">Divisione Commerciale</mds-text>\n</mds-entity>\n\n<!-- Weak tint, warning variant -->\n<mds-entity icon=\"mi/baseline/warning\" variant=\"warning\" tone=\"weak\">\n <mds-text truncate=\"word\" typography=\"h6\">Alert configurazione</mds-text>\n</mds-entity>\n```\n\n#### Await / Loading State\n\nSet the `await` boolean attribute while the entity data is being fetched. The avatar is hidden and a spinner appears in its place. Remove the attribute when loading is complete - do not set `await=\"false\"`.\n\n```html\n<mds-entity await icon=\"mi/baseline/done\" variant=\"success\">\n <mds-text truncate=\"word\" typography=\"h6\">Caricamento in corso...</mds-text>\n <mds-text truncate=\"word\" slot=\"detail\" typography=\"caption\">Attendere prego</mds-text>\n</mds-entity>\n```\n\n#### Upload / Async Workflow\n\nCombine `await` with `icon` and `variant` to drive a state machine: show the spinner while uploading, then reveal the result icon when done.\n\n```html\n<!-- While uploading -->\n<mds-entity await>\n <mds-text truncate=\"word\" typography=\"h6\">Report finanziario 2024.docx</mds-text>\n <mds-text truncate=\"word\" slot=\"detail\" typography=\"caption\">Upload in corso...</mds-text>\n <mds-button slot=\"action\" icon=\"mi/baseline/cancel\" variant=\"light\" title=\"Annulla upload\"></mds-button>\n</mds-entity>\n\n<!-- After success -->\n<mds-entity icon=\"mi/baseline/done\" variant=\"success\" tone=\"weak\">\n <mds-text truncate=\"word\" typography=\"h6\">Report finanziario 2024.docx</mds-text>\n <mds-text truncate=\"word\" slot=\"detail\" typography=\"caption\">Upload completato con successo</mds-text>\n</mds-entity>\n```\n\n#### Styling Customization\n\nStyle the entity only through its documented `--mds-entity-*` CSS custom properties. Set them on the host or a parent selector; use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.entity-highlight mds-entity {\n --mds-entity-background: rgb(var(--variant-primary-09));\n --mds-entity-color: rgb(var(--variant-primary-02));\n --mds-entity-detail-color: rgb(var(--variant-primary-04));\n --mds-entity-icon-background: rgb(var(--variant-primary-07));\n --mds-entity-icon-color: rgb(var(--variant-primary-03));\n}\n```\n",
|
|
8362
8300
|
"3. Antipattern": "Common incorrect uses of `<mds-entity>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Put the Name as a Plain Text String in the Default Slot\n\nThe default slot accepts HTML elements and components, and the component applies truncation to slotted nodes. Passing a bare string bypasses `<mds-text>` typography tokens and truncation utilities; the result may overflow or render with inconsistent styles.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-entity src=\"/avatars/mario-rossi.png\">\n Mario Rossi\n</mds-entity>\n\n<!-- ✅ CORRECT -->\n<mds-entity src=\"/avatars/mario-rossi.png\">\n <mds-text truncate=\"word\" typography=\"h6\">Mario Rossi</mds-text>\n</mds-entity>\n```\n\n#### Do Not Use `await=\"false\"` to Cancel the Loading State\n\n`await` is a boolean attribute. Setting `await=\"false\"` is still a truthy string value - the spinner stays visible. Remove the attribute (or set the prop to `undefined`) to exit the loading state.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-entity await=\"false\" src=\"/avatars/mario-rossi.png\">\n <mds-text truncate=\"word\" typography=\"h6\">Mario Rossi</mds-text>\n</mds-entity>\n\n<!-- ✅ CORRECT -->\n<mds-entity src=\"/avatars/mario-rossi.png\">\n <mds-text truncate=\"word\" typography=\"h6\">Mario Rossi</mds-text>\n</mds-entity>\n```\n\n#### Do Not Put Non-Button Elements in the `action` Slot\n\nThe `action` slot is sized and spaced for icon-only `<mds-button>` elements. Projecting arbitrary elements (raw `<button>`, `<a>`, large widgets) breaks the fixed square dimensions applied by `::slotted([slot='action'])`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-entity src=\"/avatars/mario-rossi.png\">\n <mds-text truncate=\"word\" typography=\"h6\">Mario Rossi</mds-text>\n <button slot=\"action\">Modifica</button>\n</mds-entity>\n\n<!-- ✅ CORRECT -->\n<mds-entity src=\"/avatars/mario-rossi.png\">\n <mds-text truncate=\"word\" typography=\"h6\">Mario Rossi</mds-text>\n <mds-button slot=\"action\" icon=\"mdi/pencil\" variant=\"primary\" tone=\"strong\" title=\"Modifica\"></mds-button>\n</mds-entity>\n```\n\n#### Do Not Combine `src`, `icon`, and `initials` Expecting All Three to Show\n\nThe component resolves to a single avatar representation. Only one source is shown at a time - the priority order is `src`, then `icon`, then `initials`. Setting all three does not create a layered avatar; the lower-priority sources are silently ignored.\n\n```html\n<!-- 🚫 INCORRECT (expects image, icon, and initials to all appear) -->\n<mds-entity src=\"/avatars/mario-rossi.png\" icon=\"mi/baseline/person\" initials=\"mr\">\n <mds-text truncate=\"word\" typography=\"h6\">Mario Rossi</mds-text>\n</mds-entity>\n\n<!-- ✅ CORRECT - provide the most specific source available -->\n<mds-entity src=\"/avatars/mario-rossi.png\">\n <mds-text truncate=\"word\" typography=\"h6\">Mario Rossi</mds-text>\n</mds-entity>\n```\n\n#### Do Not Apply an Invalid `tone` Value\n\n`<mds-entity>` uses `ToneMinimalVariantType`, which accepts only `strong` and `weak`. Passing other tone values like `outline` or `text` is a type error and will silently fall back, leaving the avatar unstyled.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-entity icon=\"mi/baseline/business\" variant=\"primary\" tone=\"outline\">\n <mds-text truncate=\"word\" typography=\"h6\">Divisione Commerciale</mds-text>\n</mds-entity>\n\n<!-- ✅ CORRECT -->\n<mds-entity icon=\"mi/baseline/business\" variant=\"primary\" tone=\"strong\">\n <mds-text truncate=\"word\" typography=\"h6\">Divisione Commerciale</mds-text>\n</mds-entity>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Avatar\n\nThe component exposes a `::part(avatar)` surface for styling the inner `<mds-avatar>`, but only for documented properties. Use `--mds-entity-icon-background`, `--mds-entity-icon-color`, and other `--mds-entity-*` custom properties for color customization; do not target undocumented internals.\n\n```css\n/* 🚫 INCORRECT */\nmds-entity::part(avatar) .inner-circle {\n background: hotpink;\n}\nmds-entity >>> mds-avatar {\n width: 80px;\n}\n\n/* ✅ CORRECT */\nmds-entity {\n --mds-entity-icon-background: rgb(var(--variant-primary-07));\n --mds-entity-icon-color: rgb(var(--variant-primary-03));\n}\n```\n"
|
|
8363
8301
|
},
|
|
@@ -8693,8 +8631,8 @@
|
|
|
8693
8631
|
"docsTags": [],
|
|
8694
8632
|
"usage": {
|
|
8695
8633
|
"1. Description": "The `<mds-file>` web component is the Magma Design System control for representing a downloadable file as a rich, clickable card. It pairs a filename with an auto-detected file-type icon, badge, and human-readable description, and tracks whether the file has already been downloaded.\n\n#### Semantic Behavior\n\n- **Clickable card**: The whole host is focusable and clicking it emits `mdsFileDownload`; the component itself does not fetch or download - the consumer wires the actual download to that event.\n- **Download event payload**: `mdsFileDownload` carries the resolved `description`, `extension`, `filename`, the host element as `target`, and the detected `type`/format.\n- **Downloaded persistence**: On click the component remembers the file as downloaded and shows a \"done\" indicator on subsequent renders; the state survives reloads.\n- **Automatic file-type recognition**: From `filename` it derives the format icon, badge variant, and default description; `suffix` overrides this detection.\n- **Localization**: Descriptions and the \"already downloaded\" tooltip are resolved against the active locale.\n\n#### Properties & Visual Configurations\n\n- **`filename`** is the primary input: it provides the displayed title and drives icon, badge, suffix, and description detection. The name and extension are rendered separately, with the extension shown only when not explicitly overridden by `suffix`.\n- **`suffix`** forces a specific file type from the supported format set when the filename's extension is missing or wrong; it bypasses automatic recognition.\n- **`description`** overrides the derived, localized file-type description when a custom label is needed.\n- **`preview`** supplies an image URL (logo or thumbnail) rendered as the preview surface instead of the generic format icon - use it when a meaningful visual of the file exists.\n- **`hideDownloadedIcon`** (default `false`) suppresses the persisted \"already downloaded\" indicator; set it when that affordance is not appropriate.\n- **`format`** is normally populated by the component itself from detection rather than set by the consumer.\n",
|
|
8696
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-file>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic File Card\n\nThe minimal form. Pass `filename` with a real filename (including extension) and the component auto-detects the format icon, badge color, and localized description.\n\n```html\n<mds-file filename=\"relazione-annuale.pdf\"></mds-file>\n```\n\n#### Handling the Download Event\n\nThe component does not fetch or download anything by itself. Listen for `mdsFileDownload` and trigger the actual download in the event handler. The event detail carries `filename`, `extension`, `type`, `description`, and `target`.\n\n```html\n<mds-file filename=\"contratto-servizio.docx\" id=\"file-card\"></mds-file>\n\n<script>\n document.getElementById('file-card').addEventListener('mdsFileDownload', (event) => {\n const { filename, extension, type } = event.detail;\n console.log(`Download avviato: ${filename} (${type})`);\n // avvia il download effettivo dal server\n });\n</script>\n```\n\n#### Forcing a File Type with `suffix`\n\nWhen the filename lacks an extension or carries a misleading one, use `suffix` to force a specific format from the supported set.\n\n```html\n<!-- filename senza estensione - forza il riconoscimento come PDF -->\n<mds-file filename=\"documento-firmato\" suffix=\"pdf\"></mds-file>\n\n<!-- estensione sconosciuta - forzata come archivio ZIP -->\n<mds-file filename=\"backup.bkp\" suffix=\"zip\"></mds-file>\n```\n\n#### Custom Description\n\nOverride the localized auto-generated description with a specific label relevant to the document context. Use `description` when the default type label (e.g. \"Documento PDF\") is not informative enough.\n\n```html\n<mds-file\n filename=\"verbale-cda-2024.pdf\"\n description=\"Verbale approvato dal Consiglio di Amministrazione\"\n></mds-file>\n```\n\n#### Image Preview\n\nProvide `preview` with an image URL when a meaningful visual thumbnail is available - a logo, a reduced version of an image file, or a document cover. The preview replaces the generic format icon in the left panel.\n\n```html\n<mds-file\n filename=\"logo-aziendale.png\"\n preview=\"https://cdn.example.com/thumbnails/logo-aziendale-128.png\"\n></mds-file>\n```\n\n#### Hiding the \"Already Downloaded\" Indicator\n\nBy default the component persists a \"done\" indicator once the file has been downloaded. Add `hide-downloaded-icon` to suppress it when the affordance is not appropriate for the context (e.g. a list where every file is always shown as fresh).\n\n```html\n<mds-file filename=\"modulo-richiesta.xlsx\" hide-downloaded-icon></mds-file>\n```\n\nNote: this is the only valid way to turn the indicator off - do not set it to the string `\"false\"` (see the Antipattern file).\n\n#### Rendering a List of Files\n\nPlace multiple `<mds-file>` cards inside a container and attach a single delegated event listener when the file list is dynamic.\n\n```html\n<div class=\"file-list\">\n <mds-file filename=\"allegato-1.pdf\"></mds-file>\n <mds-file filename=\"allegato-2.docx\"></mds-file>\n <mds-file filename=\"allegato-3.xlsx\"></mds-file>\n</div>\n\n<script>\n document.querySelector('.file-list').addEventListener('mdsFileDownload', (event) => {\n const { filename } = event.detail;\n avviaDownload(filename);\n });\n</script>\n```\n\n#### Styling Customization\n\nStyle the preview panel only through the three documented `--mds-file-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.archivio-documenti mds-file {\n --mds-file-preview-icon-color: rgb(var(--variant-primary-04));\n --mds-file-preview-icon-
|
|
8697
|
-
"3. Antipattern": "Common incorrect uses of `<mds-file>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Expect the Component to Perform the Download\n\n`<mds-file>` is a display card, not a download trigger. It emits `mdsFileDownload` and the consumer must wire the actual download logic to that event.\n\n```html\n<!-- 🚫 INCORRECT - expecting the component to handle the download itself -->\n<mds-file filename=\"report.pdf\" href=\"/files/report.pdf\"></mds-file>\n\n<!-- ✅ CORRECT - consumer listens to the event and handles the download -->\n<mds-file filename=\"report.pdf\" id=\"card-report\"></mds-file>\n\n<script>\n document.getElementById('card-report').addEventListener('mdsFileDownload', (e) => {\n window.location.href = '/files/' + e.detail.filename;\n });\n</script>\n```\n\n#### Do Not Set `format` Manually\n\n`format` is an internal reflected attribute automatically derived from the filename and suffix. Setting it directly has no guaranteed effect because the component overwrites it during `componentWillLoad` and on every `filename` change. Use `suffix` to control type detection.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-file filename=\"archivio\" format=\"document\"></mds-file>\n\n<!-- ✅ CORRECT - use suffix to override file-type detection -->\n<mds-file filename=\"archivio\" suffix=\"pdf\"></mds-file>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Preview Panel\n\nThe supported customization surface is `--mds-file-preview-*` CSS custom properties. Targeting internal elements with `>>>`, `/deep/`, or undocumented selectors couples your code to the Shadow DOM structure and will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-file >>> .preview {\n background-color: blue;\n}\n\n/* ✅ CORRECT */\nmds-file {\n --mds-file-preview-icon-
|
|
8634
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-file>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic File Card\n\nThe minimal form. Pass `filename` with a real filename (including extension) and the component auto-detects the format icon, badge color, and localized description.\n\n```html\n<mds-file filename=\"relazione-annuale.pdf\"></mds-file>\n```\n\n#### Handling the Download Event\n\nThe component does not fetch or download anything by itself. Listen for `mdsFileDownload` and trigger the actual download in the event handler. The event detail carries `filename`, `extension`, `type`, `description`, and `target`.\n\n```html\n<mds-file filename=\"contratto-servizio.docx\" id=\"file-card\"></mds-file>\n\n<script>\n document.getElementById('file-card').addEventListener('mdsFileDownload', (event) => {\n const { filename, extension, type } = event.detail;\n console.log(`Download avviato: ${filename} (${type})`);\n // avvia il download effettivo dal server\n });\n</script>\n```\n\n#### Forcing a File Type with `suffix`\n\nWhen the filename lacks an extension or carries a misleading one, use `suffix` to force a specific format from the supported set.\n\n```html\n<!-- filename senza estensione - forza il riconoscimento come PDF -->\n<mds-file filename=\"documento-firmato\" suffix=\"pdf\"></mds-file>\n\n<!-- estensione sconosciuta - forzata come archivio ZIP -->\n<mds-file filename=\"backup.bkp\" suffix=\"zip\"></mds-file>\n```\n\n#### Custom Description\n\nOverride the localized auto-generated description with a specific label relevant to the document context. Use `description` when the default type label (e.g. \"Documento PDF\") is not informative enough.\n\n```html\n<mds-file\n filename=\"verbale-cda-2024.pdf\"\n description=\"Verbale approvato dal Consiglio di Amministrazione\"\n></mds-file>\n```\n\n#### Image Preview\n\nProvide `preview` with an image URL when a meaningful visual thumbnail is available - a logo, a reduced version of an image file, or a document cover. The preview replaces the generic format icon in the left panel.\n\n```html\n<mds-file\n filename=\"logo-aziendale.png\"\n preview=\"https://cdn.example.com/thumbnails/logo-aziendale-128.png\"\n></mds-file>\n```\n\n#### Hiding the \"Already Downloaded\" Indicator\n\nBy default the component persists a \"done\" indicator once the file has been downloaded. Add `hide-downloaded-icon` to suppress it when the affordance is not appropriate for the context (e.g. a list where every file is always shown as fresh).\n\n```html\n<mds-file filename=\"modulo-richiesta.xlsx\" hide-downloaded-icon></mds-file>\n```\n\nNote: this is the only valid way to turn the indicator off - do not set it to the string `\"false\"` (see the Antipattern file).\n\n#### Rendering a List of Files\n\nPlace multiple `<mds-file>` cards inside a container and attach a single delegated event listener when the file list is dynamic.\n\n```html\n<div class=\"file-list\">\n <mds-file filename=\"allegato-1.pdf\"></mds-file>\n <mds-file filename=\"allegato-2.docx\"></mds-file>\n <mds-file filename=\"allegato-3.xlsx\"></mds-file>\n</div>\n\n<script>\n document.querySelector('.file-list').addEventListener('mdsFileDownload', (event) => {\n const { filename } = event.detail;\n avviaDownload(filename);\n });\n</script>\n```\n\n#### Styling Customization\n\nStyle the preview panel only through the three documented `--mds-file-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.archivio-documenti mds-file {\n --mds-file-preview-icon-color: rgb(var(--variant-primary-04));\n --mds-file-preview-icon-background: rgb(var(--variant-primary-10));\n --mds-file-preview-color: rgb(var(--variant-primary-04));\n}\n```\n",
|
|
8635
|
+
"3. Antipattern": "Common incorrect uses of `<mds-file>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Expect the Component to Perform the Download\n\n`<mds-file>` is a display card, not a download trigger. It emits `mdsFileDownload` and the consumer must wire the actual download logic to that event.\n\n```html\n<!-- 🚫 INCORRECT - expecting the component to handle the download itself -->\n<mds-file filename=\"report.pdf\" href=\"/files/report.pdf\"></mds-file>\n\n<!-- ✅ CORRECT - consumer listens to the event and handles the download -->\n<mds-file filename=\"report.pdf\" id=\"card-report\"></mds-file>\n\n<script>\n document.getElementById('card-report').addEventListener('mdsFileDownload', (e) => {\n window.location.href = '/files/' + e.detail.filename;\n });\n</script>\n```\n\n#### Do Not Set `format` Manually\n\n`format` is an internal reflected attribute automatically derived from the filename and suffix. Setting it directly has no guaranteed effect because the component overwrites it during `componentWillLoad` and on every `filename` change. Use `suffix` to control type detection.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-file filename=\"archivio\" format=\"document\"></mds-file>\n\n<!-- ✅ CORRECT - use suffix to override file-type detection -->\n<mds-file filename=\"archivio\" suffix=\"pdf\"></mds-file>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Preview Panel\n\nThe supported customization surface is `--mds-file-preview-*` CSS custom properties. Targeting internal elements with `>>>`, `/deep/`, or undocumented selectors couples your code to the Shadow DOM structure and will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-file >>> .preview {\n background-color: blue;\n}\n\n/* ✅ CORRECT */\nmds-file {\n --mds-file-preview-icon-background: rgb(var(--variant-primary-10));\n --mds-file-preview-icon-color: rgb(var(--variant-primary-04));\n}\n```\n\n#### Do Not Wrap `<mds-file>` in a Native Anchor or Button\n\nThe host is already focusable, keyboard-accessible, and emits its own interaction event. Wrapping it in `<a>` or `<button>` creates nested interactive controls and breaks keyboard semantics.\n\n```html\n<!-- 🚫 INCORRECT -->\n<a href=\"/download/report.pdf\">\n <mds-file filename=\"report.pdf\"></mds-file>\n</a>\n\n<!-- ✅ CORRECT - use the mdsFileDownload event to trigger navigation or download -->\n<mds-file filename=\"report.pdf\" id=\"file-report\"></mds-file>\n\n<script>\n document.getElementById('file-report').addEventListener('mdsFileDownload', () => {\n window.location.href = '/download/report.pdf';\n });\n</script>\n```\n\n#### Do Not Use a Raw `<div>` or `<li>` as a File Row When `<mds-file>` Exists\n\n`<mds-file>` handles format detection, theming, accessibility focus, download persistence, and localization. Rolling a custom file row loses all of these affordances.\n\n```html\n<!-- 🚫 INCORRECT -->\n<div class=\"file-row\" onclick=\"download('report.pdf')\">\n <img src=\"pdf-icon.svg\" alt=\"PDF\" />\n <span>report.pdf</span>\n</div>\n\n<!-- ✅ CORRECT -->\n<mds-file filename=\"report.pdf\"></mds-file>\n```\n"
|
|
8698
8636
|
},
|
|
8699
8637
|
"props": [
|
|
8700
8638
|
{
|
|
@@ -9097,30 +9035,7 @@
|
|
|
9097
9035
|
"setter": false
|
|
9098
9036
|
}
|
|
9099
9037
|
],
|
|
9100
|
-
"methods": [
|
|
9101
|
-
{
|
|
9102
|
-
"name": "updateLang",
|
|
9103
|
-
"returns": {
|
|
9104
|
-
"type": "Promise<void>",
|
|
9105
|
-
"docs": ""
|
|
9106
|
-
},
|
|
9107
|
-
"complexType": {
|
|
9108
|
-
"signature": "() => Promise<void>",
|
|
9109
|
-
"parameters": [],
|
|
9110
|
-
"references": {
|
|
9111
|
-
"Promise": {
|
|
9112
|
-
"location": "global",
|
|
9113
|
-
"id": "global::Promise"
|
|
9114
|
-
}
|
|
9115
|
-
},
|
|
9116
|
-
"return": "Promise<void>"
|
|
9117
|
-
},
|
|
9118
|
-
"signature": "updateLang() => Promise<void>",
|
|
9119
|
-
"parameters": [],
|
|
9120
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
9121
|
-
"docsTags": []
|
|
9122
|
-
}
|
|
9123
|
-
],
|
|
9038
|
+
"methods": [],
|
|
9124
9039
|
"events": [
|
|
9125
9040
|
{
|
|
9126
9041
|
"event": "mdsFileDownload",
|
|
@@ -9152,7 +9067,7 @@
|
|
|
9152
9067
|
"docs": "Sets the text color used in the file preview"
|
|
9153
9068
|
},
|
|
9154
9069
|
{
|
|
9155
|
-
"name": "--mds-file-preview-icon-
|
|
9070
|
+
"name": "--mds-file-preview-icon-background",
|
|
9156
9071
|
"annotation": "prop",
|
|
9157
9072
|
"docs": "Sets the background color of the file preview icon"
|
|
9158
9073
|
},
|
|
@@ -9836,30 +9751,7 @@
|
|
|
9836
9751
|
"setter": false
|
|
9837
9752
|
}
|
|
9838
9753
|
],
|
|
9839
|
-
"methods": [
|
|
9840
|
-
{
|
|
9841
|
-
"name": "updateLang",
|
|
9842
|
-
"returns": {
|
|
9843
|
-
"type": "Promise<void>",
|
|
9844
|
-
"docs": ""
|
|
9845
|
-
},
|
|
9846
|
-
"complexType": {
|
|
9847
|
-
"signature": "() => Promise<void>",
|
|
9848
|
-
"parameters": [],
|
|
9849
|
-
"references": {
|
|
9850
|
-
"Promise": {
|
|
9851
|
-
"location": "global",
|
|
9852
|
-
"id": "global::Promise"
|
|
9853
|
-
}
|
|
9854
|
-
},
|
|
9855
|
-
"return": "Promise<void>"
|
|
9856
|
-
},
|
|
9857
|
-
"signature": "updateLang() => Promise<void>",
|
|
9858
|
-
"parameters": [],
|
|
9859
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
9860
|
-
"docsTags": []
|
|
9861
|
-
}
|
|
9862
|
-
],
|
|
9754
|
+
"methods": [],
|
|
9863
9755
|
"events": [
|
|
9864
9756
|
{
|
|
9865
9757
|
"event": "mdsFileDelete",
|
|
@@ -10948,7 +10840,7 @@
|
|
|
10948
10840
|
}
|
|
10949
10841
|
],
|
|
10950
10842
|
"usage": {
|
|
10951
|
-
"1. Description": "The `<mds-header-bar>` web component is the top bar of a Magma application layout: it holds the product branding on the left and the primary navigation actions on the right, collapsing those actions into a hamburger menu on smaller viewports. It is a structural compound element, typically nested inside an `<mds-header>`, with no native HTML primitive equivalent.\n\n#### Semantic Behavior\n\n- **Branding region**: The default (unnamed) slot is the logo/branding area on the left; place text, HTML, or components such as a logo with a short description here.\n- **Navigation region**: The `nav` named slot holds the horizontal desktop actions, wrapped in a real `<nav>` element; `mds-button` elements are the recommended children.\n- **Conditional nav rendering**: The `<nav>` is
|
|
10843
|
+
"1. Description": "The `<mds-header-bar>` web component is the top bar of a Magma application layout: it holds the product branding on the left and the primary navigation actions on the right, collapsing those actions into a hamburger menu on smaller viewports. It is a structural compound element, typically nested inside an `<mds-header>`, with no native HTML primitive equivalent.\n\n#### Semantic Behavior\n\n- **Branding region**: The default (unnamed) slot is the logo/branding area on the left; place text, HTML, or components such as a logo with a short description here.\n- **Navigation region**: The `nav` named slot holds the horizontal desktop actions, wrapped in a real `<nav>` element; `mds-button` elements are the recommended children.\n- **Conditional nav rendering**: The `<nav>` is shown only when `nav` is not `'none'` and a `slot=\"nav\"` child is present, also when it is added after the first render, so an empty header collapses cleanly.\n- **Hamburger trigger**: When `menu` is not `'none'` the component renders a menu button that opens the menu on click.\n- **Open event**: Clicking the hamburger emits the bubbling `mdsHeaderBarOpen` event and opens the drawer on the surrounding `mds-header`.\n- **Imperative open control**: The public `setOpened(isOpened = true)` method lets a parent or script toggle the opened state programmatically.\n\n#### Properties & Visual Configurations\n\nThe two props are both responsive visibility switches sharing the value set `'all' | 'desktop' | 'mobile' | 'none'`, where the value names the breakpoint(s) at which the region is shown (`'none'` hides it entirely, `'all'` always shows it).\n\n- **`menu`** controls when the hamburger button appears. It defaults to `'mobile'`, so the collapsed menu surfaces only on small screens; set it to `'all'` to always expose the menu trigger or `'none'` to suppress it.\n- **`nav`** controls when the inline horizontal navigation is shown. It defaults to `'desktop'`, the typical complement to `menu`: links sit inline on wide viewports and fold into the hamburger on narrow ones.\n",
|
|
10952
10844
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-header-bar>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Standard Header Bar with Logo and Navigation\n\nThe canonical form. Place branding content in the default slot (left side) and `<mds-button>` elements in the `nav` slot (right side). With the defaults (`menu=\"mobile\"` and `nav=\"desktop\"`) the nav is visible on desktop and the hamburger appears only on mobile.\n\n```html\n<mds-header-bar>\n <div class=\"flex gap-200 items-center\">\n <mds-img src=\"./logo.svg\" />\n <mds-text typography=\"h6\">Portale Enti</mds-text>\n </div>\n <mds-button slot=\"nav\" variant=\"dark\" tone=\"outline\">Accedi</mds-button>\n <mds-button slot=\"nav\" variant=\"primary\" tone=\"strong\">Registrati</mds-button>\n</mds-header-bar>\n```\n\n#### Nested Inside `mds-header`\n\n`<mds-header-bar>` is a structural sub-component of [`mds-header`](../../mds-header). Place it inside `<mds-header>` so that the hamburger click is wired to the drawer automatically; the component calls `mds-header.setOpened(true)` on its nearest `mds-header` ancestor.\n\n```html\n<mds-header>\n <mds-header-bar>\n <mds-text typography=\"h6\">Gestione Pratiche</mds-text>\n <mds-button slot=\"nav\" variant=\"dark\" tone=\"text\" icon=\"mi/baseline/person\">Account</mds-button>\n <mds-button slot=\"nav\" variant=\"primary\" tone=\"strong\">Nuovo documento</mds-button>\n </mds-header-bar>\n <!-- drawer and other header regions go here -->\n</mds-header>\n```\n\n#### Controlling Hamburger Visibility\n\nUse the `menu` prop to decide when the hamburger button is shown. The default `mobile` is correct for most apps. Use `all` when you always want a drawer-style menu regardless of viewport, or `none` to remove the hamburger entirely (e.g. a public marketing bar with no drawer).\n\n```html\n<!-- Always show the hamburger (single-column layout, any viewport) -->\n<mds-header-bar menu=\"all\">\n <mds-text typography=\"h6\">Area Personale</mds-text>\n</mds-header-bar>\n\n<!-- No hamburger at all (branding-only bar) -->\n<mds-header-bar menu=\"none\">\n <mds-img src=\"./logo.svg\" />\n</mds-header-bar>\n```\n\n#### Controlling Inline Navigation Visibility\n\nUse the `nav` prop symmetrically with `menu`. The default `desktop` shows the nav slot only on wide viewports. Set `nav=\"all\"` to always show inline links, `nav=\"mobile\"` to show them only on small screens, or `nav=\"none\"` to suppress the nav region entirely.\n\n```html\n<!-- Always show inline nav (no responsive collapsing) -->\n<mds-header-bar menu=\"none\" nav=\"all\">\n <mds-img src=\"./logo.svg\" />\n <mds-button slot=\"nav\" variant=\"dark\" tone=\"text\">Chi siamo</mds-button>\n <mds-button slot=\"nav\" variant=\"dark\" tone=\"text\">Servizi</mds-button>\n <mds-button slot=\"nav\" variant=\"primary\" tone=\"strong\">Contatti</mds-button>\n</mds-header-bar>\n```\n\n#### Listening for the Hamburger Open Event\n\nListen to `mdsHeaderBarOpen` (bubbles) to react when the user taps the hamburger - for example to track analytics or to open a custom side panel not managed by `mds-header`.\n\n```html\n<mds-header-bar id=\"main-bar\">\n <mds-text typography=\"h6\">Applicazione</mds-text>\n</mds-header-bar>\n\n<script>\n document.getElementById('main-bar').addEventListener('mdsHeaderBarOpen', () => {\n console.log('menu aperto');\n });\n</script>\n```\n\n#### Programmatic Open via `setOpened`\n\nCall the `setOpened(isOpened)` public method to toggle the opened state from external code - for instance after route navigation in a single-page app.\n\n```html\n<mds-header-bar id=\"main-bar\">\n <mds-text typography=\"h6\">Dashboard</mds-text>\n</mds-header-bar>\n\n<script>\n // Close the bar after the user selects a menu item\n const bar = document.getElementById('main-bar');\n bar.setOpened(false);\n</script>\n```\n\n#### Styling the Hamburger Icon Color\n\nUse `--mds-header-bar-hamburger-color` to theme the hamburger icon. Set it on the host element or a parent selector; use a Magma color token wrapped with `rgb(var(...))` so dark-mode works automatically.\n\n```css\nmds-header-bar {\n --mds-header-bar-hamburger-color: rgb(var(--variant-primary-03));\n}\n```\n\n#### Styling via Shadow Parts\n\nThe four documented shadow parts (`content`, `actions`, `nav`, `hamburger`) let you adjust layout without piercing the shadow DOM. Target only these documented parts.\n\n```css\n/* Increase the gap between the nav buttons and the hamburger */\nmds-header-bar::part(actions) {\n gap: var(--spacing-600);\n}\n\n/* Visually highlight the hamburger button in a branded theme */\nmds-header-bar::part(hamburger) {\n border-radius: var(--radius-md);\n background-color: rgb(var(--variant-primary-02));\n}\n```\n",
|
|
10953
10845
|
"3. Antipattern": "Common incorrect uses of `<mds-header-bar>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use `mds-header-bar` Standalone Outside `mds-header`\n\n`<mds-header-bar>` is a structural sub-component of [`mds-header`](../../mds-header). Used alone, the hamburger click has no `mds-header` ancestor to call `setOpened` on, so the drawer never opens. Always place it inside `<mds-header>` unless you have fully replaced drawer management with `mdsHeaderBarOpen` listeners.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-header-bar>\n <mds-text typography=\"h6\">Portale</mds-text>\n</mds-header-bar>\n\n<!-- ✅ CORRECT -->\n<mds-header>\n <mds-header-bar>\n <mds-text typography=\"h6\">Portale</mds-text>\n </mds-header-bar>\n</mds-header>\n```\n\n#### Do Not Put Navigation Links in the Default Slot\n\nThe default slot is the branding region (left side). Navigation actions must go in the `nav` named slot so the component can apply responsive visibility rules and wrap them in the `<nav>` element for landmark semantics.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-header-bar>\n <mds-img src=\"./logo.svg\" />\n <mds-button variant=\"dark\" tone=\"text\">Servizi</mds-button>\n <mds-button variant=\"primary\" tone=\"strong\">Accedi</mds-button>\n</mds-header-bar>\n\n<!-- ✅ CORRECT -->\n<mds-header-bar>\n <mds-img src=\"./logo.svg\" />\n <mds-button slot=\"nav\" variant=\"dark\" tone=\"text\">Servizi</mds-button>\n <mds-button slot=\"nav\" variant=\"primary\" tone=\"strong\">Accedi</mds-button>\n</mds-header-bar>\n```\n\n#### Do Not Set Both `menu` and `nav` to `none` Without a Replacement\n\nSetting both to `none` hides all interactive regions and leaves a branding-only bar with no way to navigate, which is rarely the intended result. If the design truly needs a pure branding strip, be explicit about it and confirm it is intentional; otherwise keep at least one region visible.\n\n```html\n<!-- 🚫 INCORRECT (navigation is invisible and unreachable) -->\n<mds-header-bar menu=\"none\" nav=\"none\">\n <mds-img src=\"./logo.svg\" />\n</mds-header-bar>\n\n<!-- ✅ CORRECT (branding-only bar is an intentional design choice, documented) -->\n<!-- Only do this when no navigation is needed on the page (e.g. login screen) -->\n<mds-header-bar menu=\"none\" nav=\"none\">\n <mds-img src=\"./logo.svg\" />\n</mds-header-bar>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Hamburger or Nav\n\nThe only documented customization hooks are `--mds-header-bar-hamburger-color` (CSS custom property) and the shadow parts `content`, `actions`, `nav`, `hamburger`. Targeting undocumented internal classes couples your code to implementation details that can change at any minor release.\n\n```css\n/* 🚫 INCORRECT */\nmds-header-bar >>> .menu {\n fill: red;\n}\nmds-header-bar::part(icon) {\n fill: blue;\n}\n\n/* ✅ CORRECT */\nmds-header-bar {\n --mds-header-bar-hamburger-color: rgb(var(--variant-primary-03));\n}\nmds-header-bar::part(hamburger) {\n background-color: rgb(var(--tone-neutral-02));\n}\n```\n\n#### Do Not Listen to `click` on the Hamburger Instead of `mdsHeaderBarOpen`\n\nThe hamburger button lives inside shadow DOM; a `click` listener on the host may not behave as expected across all frameworks and browsers. Use the documented `mdsHeaderBarOpen` event, which bubbles and is the intended communication channel.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-header-bar id=\"bar\">...</mds-header-bar>\n<script>\n document.getElementById('bar').addEventListener('click', handleMenu);\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-header-bar id=\"bar\">...</mds-header-bar>\n<script>\n document.getElementById('bar').addEventListener('mdsHeaderBarOpen', handleMenu);\n</script>\n```\n\n#### Do Not Set `menu` or `nav` to an Undocumented String Value\n\nThe accepted values for both props are `'all' | 'desktop' | 'mobile' | 'none'`. Strings outside that set are silently ignored and the component falls back to the default, producing unexpected layout.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-header-bar menu=\"always\" nav=\"never\">...</mds-header-bar>\n<mds-header-bar menu=\"true\" nav=\"false\">...</mds-header-bar>\n\n<!-- ✅ CORRECT -->\n<mds-header-bar menu=\"all\" nav=\"none\">...</mds-header-bar>\n```\n"
|
|
10954
10846
|
},
|
|
@@ -11394,7 +11286,7 @@
|
|
|
11394
11286
|
],
|
|
11395
11287
|
"usage": {
|
|
11396
11288
|
"1. Description": "The `<mds-horizontal-scroll>` web component is a horizontally scrolling container of the Magma Design System. It wraps any slotted content in a snap-scrolling viewport and overlays optional navigation controls, replacing the manual overflow/scroll-snap CSS plumbing you would otherwise write around a `<div>`.\n\n#### Semantic Behavior\n\n- **Slotted children drive scrolling**: The default slot's children are the scrollable items.\n- **Navigation buttons**: When `controls` resolves to a viewport other than `'none'`, two arrow buttons are rendered; each advances the scroll position to the next/previous item not fully in the viewport.\n- **Auto-disabled arrows**: The back arrow hides/disables when the first item is fully visible and the forward arrow when the last item is.\n- **Position indicator**: With `navigation=\"position\"` a proportional dot is rendered; its width reflects the visible/total ratio and it translates along its track as the container scrolls.\n- **No focus or form semantics**: This is a presentational scroll container - it is not form-associated, exposes no implicit ARIA role, and emits no custom events.\n\n#### Properties & Visual Configurations\n\n- **`controls`** selects the largest viewport breakpoint at which the arrow navigation appears (default `'desktop'`); pick a wider tier like `'large'` or `'wide'` to show arrows only on big screens, or `'none'` to suppress them entirely. The chosen value is the threshold, not a single device.\n- **`navigation`** chooses the scroll-progress affordance: `'position'` renders the translating dot indicator, `'scrollbar'` defers to the styled native browser scrollbar, and `'none'` shows neither.\n- **`snap`** sets the scroll-snap alignment of each item against the viewport - `'start'` (default) aligns items to the leading edge, `'center'` keeps them centred, `'end'` to the trailing edge, and `'none'` disables snapping for free scrolling.\n\nThis component does not use the shared `variant` / `tone` ladders defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); appearance is tuned entirely through its CSS custom properties (see readme.md).\n",
|
|
11397
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-horizontal-scroll>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the conventions in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Horizontal Scroll with Cards\n\nThe canonical form. Slot any fixed-width children directly into the component; it wraps them in a snap-scrolling viewport with a proportional dot indicator and arrow buttons automatically.\n\n```html\n<mds-horizontal-scroll>\n <mds-card class=\"min-w-[320px]\">\n <mds-card-header>Servizio 1</mds-card-header>\n <mds-card-content>Descrizione del primo servizio.</mds-card-content>\n </mds-card>\n <mds-card class=\"min-w-[320px]\">\n <mds-card-header>Servizio 2</mds-card-header>\n <mds-card-content>Descrizione del secondo servizio.</mds-card-content>\n </mds-card>\n <mds-card class=\"min-w-[320px]\">\n <mds-card-header>Servizio 3</mds-card-header>\n <mds-card-content>Descrizione del terzo servizio.</mds-card-content>\n </mds-card>\n</mds-horizontal-scroll>\n```\n\n#### Controlling Navigation Arrow Visibility\n\nUse `controls` to restrict arrow buttons to specific viewport tiers. The value is the minimum breakpoint at which arrows appear - `'desktop'` (default) shows them only on desktop and above; `'all'` shows them at every viewport size; `'none'` suppresses them entirely.\n\n```html\n<!-- Arrows only on desktop and above (default) -->\n<mds-horizontal-scroll controls=\"desktop\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n\n<!-- Arrows on all viewports, including mobile -->\n<mds-horizontal-scroll controls=\"all\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n\n<!-- No arrows - touch / keyboard scroll only -->\n<mds-horizontal-scroll controls=\"none\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n```\n\n#### Scroll Progress Indicator\n\nUse `navigation` to choose the scroll-position affordance shown below the items. `'position'` (default) renders a proportional translating dot; `'scrollbar'` defers to the styled native browser scrollbar; `'none'` hides both.\n\n```html\n<!-- Dot indicator (default) -->\n<mds-horizontal-scroll navigation=\"position\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n\n<!-- Native scrollbar instead of dot -->\n<mds-horizontal-scroll navigation=\"scrollbar\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n\n<!-- No progress indicator -->\n<mds-horizontal-scroll navigation=\"none\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n```\n\n#### Snap Alignment\n\n`snap` controls how each item aligns to the viewport edge when the scroll settles. Use `'start'` (default) for left-aligned cards, `'center'` for centred carousels, `'end'` for right-aligned layouts, or `'none'` to allow free scrolling without snapping.\n\n```html\n<!-- Leading-edge alignment (default, most common) -->\n<mds-horizontal-scroll snap=\"start\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n\n<!-- Centred alignment - good for full-bleed hero carousels -->\n<mds-horizontal-scroll snap=\"center\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n\n<!-- Free scroll - no snapping -->\n<mds-horizontal-scroll snap=\"none\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n```\n\n#### Combining Props for a Mobile-Friendly Carousel\n\nPair `controls=\"all\"` with `snap=\"center\"` and `navigation=\"position\"` to produce a touch-and-arrow carousel that works at every breakpoint.\n\n```html\n<mds-horizontal-scroll controls=\"all\" snap=\"center\" navigation=\"position\">\n <mds-card class=\"min-w-[280px]\">\n <mds-card-media>\n <mds-img src=\"https://example.com/img1.jpg\"></mds-img>\n </mds-card-media>\n <mds-card-content>\n <mds-text typography=\"h5\">Categoria A</mds-text>\n </mds-card-content>\n </mds-card>\n <mds-card class=\"min-w-[280px]\">\n <mds-card-media>\n <mds-img src=\"https://example.com/img2.jpg\"></mds-img>\n </mds-card-media>\n <mds-card-content>\n <mds-text typography=\"h5\">Categoria B</mds-text>\n </mds-card-content>\n </mds-card>\n</mds-horizontal-scroll>\n```\n\n#### Styling Customization\n\nStyle the component only through its documented `--mds-horizontal-scroll-*` CSS custom properties. Set them on the host or a parent selector; use Magma tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.sezione-evidenza mds-horizontal-scroll {\n --mds-horizontal-scroll-
|
|
11289
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-horizontal-scroll>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the conventions in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Horizontal Scroll with Cards\n\nThe canonical form. Slot any fixed-width children directly into the component; it wraps them in a snap-scrolling viewport with a proportional dot indicator and arrow buttons automatically.\n\n```html\n<mds-horizontal-scroll>\n <mds-card class=\"min-w-[320px]\">\n <mds-card-header>Servizio 1</mds-card-header>\n <mds-card-content>Descrizione del primo servizio.</mds-card-content>\n </mds-card>\n <mds-card class=\"min-w-[320px]\">\n <mds-card-header>Servizio 2</mds-card-header>\n <mds-card-content>Descrizione del secondo servizio.</mds-card-content>\n </mds-card>\n <mds-card class=\"min-w-[320px]\">\n <mds-card-header>Servizio 3</mds-card-header>\n <mds-card-content>Descrizione del terzo servizio.</mds-card-content>\n </mds-card>\n</mds-horizontal-scroll>\n```\n\n#### Controlling Navigation Arrow Visibility\n\nUse `controls` to restrict arrow buttons to specific viewport tiers. The value is the minimum breakpoint at which arrows appear - `'desktop'` (default) shows them only on desktop and above; `'all'` shows them at every viewport size; `'none'` suppresses them entirely.\n\n```html\n<!-- Arrows only on desktop and above (default) -->\n<mds-horizontal-scroll controls=\"desktop\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n\n<!-- Arrows on all viewports, including mobile -->\n<mds-horizontal-scroll controls=\"all\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n\n<!-- No arrows - touch / keyboard scroll only -->\n<mds-horizontal-scroll controls=\"none\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n```\n\n#### Scroll Progress Indicator\n\nUse `navigation` to choose the scroll-position affordance shown below the items. `'position'` (default) renders a proportional translating dot; `'scrollbar'` defers to the styled native browser scrollbar; `'none'` hides both.\n\n```html\n<!-- Dot indicator (default) -->\n<mds-horizontal-scroll navigation=\"position\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n\n<!-- Native scrollbar instead of dot -->\n<mds-horizontal-scroll navigation=\"scrollbar\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n\n<!-- No progress indicator -->\n<mds-horizontal-scroll navigation=\"none\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n```\n\n#### Snap Alignment\n\n`snap` controls how each item aligns to the viewport edge when the scroll settles. Use `'start'` (default) for left-aligned cards, `'center'` for centred carousels, `'end'` for right-aligned layouts, or `'none'` to allow free scrolling without snapping.\n\n```html\n<!-- Leading-edge alignment (default, most common) -->\n<mds-horizontal-scroll snap=\"start\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n\n<!-- Centred alignment - good for full-bleed hero carousels -->\n<mds-horizontal-scroll snap=\"center\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n\n<!-- Free scroll - no snapping -->\n<mds-horizontal-scroll snap=\"none\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n```\n\n#### Combining Props for a Mobile-Friendly Carousel\n\nPair `controls=\"all\"` with `snap=\"center\"` and `navigation=\"position\"` to produce a touch-and-arrow carousel that works at every breakpoint.\n\n```html\n<mds-horizontal-scroll controls=\"all\" snap=\"center\" navigation=\"position\">\n <mds-card class=\"min-w-[280px]\">\n <mds-card-media>\n <mds-img src=\"https://example.com/img1.jpg\"></mds-img>\n </mds-card-media>\n <mds-card-content>\n <mds-text typography=\"h5\">Categoria A</mds-text>\n </mds-card-content>\n </mds-card>\n <mds-card class=\"min-w-[280px]\">\n <mds-card-media>\n <mds-img src=\"https://example.com/img2.jpg\"></mds-img>\n </mds-card-media>\n <mds-card-content>\n <mds-text typography=\"h5\">Categoria B</mds-text>\n </mds-card-content>\n </mds-card>\n</mds-horizontal-scroll>\n```\n\n#### Styling Customization\n\nStyle the component only through its documented `--mds-horizontal-scroll-*` CSS custom properties. Set them on the host or a parent selector; use Magma tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.sezione-evidenza mds-horizontal-scroll {\n --mds-horizontal-scroll-gap: var(--spacing-400);\n --mds-horizontal-scroll-dot-background: rgb(var(--variant-primary-03));\n --mds-horizontal-scroll-dot-area-background: rgb(var(--variant-primary-08));\n --mds-horizontal-scroll-max-width: 1200px;\n}\n```\n\n#### Styling the Scrollbar\n\nWhen `navigation=\"scrollbar\"` is used, customize the native scrollbar appearance through the dedicated properties. All scrollbar props are browser-dependent and may have no effect on browsers that do not expose a styleable scrollbar.\n\n```css\nmds-horizontal-scroll {\n --mds-horizontal-scroll-scrollbar-size: 6px;\n --mds-horizontal-scroll-scrollbar-radius: 4px;\n --mds-horizontal-scroll-scrollbar-thumb-background: rgb(var(--variant-primary-03));\n --mds-horizontal-scroll-scrollbar-track-background: rgb(var(--tone-neutral-07));\n}\n```\n\n#### Customizing the Content Part\n\nThe inner scroll container is exposed as `::part(content)`. Use it sparingly - only when a CSS custom property cannot satisfy your requirement - to apply layout overrides without piercing undocumented internals.\n\n```css\nmds-horizontal-scroll::part(content) {\n padding-block: var(--spacing-800);\n}\n```\n",
|
|
11398
11290
|
"3. Antipattern": "Common incorrect uses of `<mds-horizontal-scroll>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Set `controls` to a Boolean\n\n`controls` is a `ViewportType` string prop, not a boolean. Setting it without a value (or as `\"\"`) coerces to a truthy string that is not a recognized viewport tier and produces undefined behavior. Always supply an explicit string value.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-horizontal-scroll controls>\n <!-- slotted items -->\n</mds-horizontal-scroll>\n\n<!-- ✅ CORRECT -->\n<mds-horizontal-scroll controls=\"desktop\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n```\n\n#### Do Not Wrap Slotted Items in an Extra Div\n\nAdding a single wrapper `<div>` around all children collapses the scroll track to one item. The component's arrow and snap logic iterates over the direct slot children - each scrollable item must be a direct child, not grandchildren inside a wrapper.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-horizontal-scroll>\n <div>\n <mds-card class=\"min-w-[320px]\">...</mds-card>\n <mds-card class=\"min-w-[320px]\">...</mds-card>\n </div>\n</mds-horizontal-scroll>\n\n<!-- ✅ CORRECT -->\n<mds-horizontal-scroll>\n <mds-card class=\"min-w-[320px]\">...</mds-card>\n <mds-card class=\"min-w-[320px]\">...</mds-card>\n</mds-horizontal-scroll>\n```\n\n#### Do Not Set `controls=\"none\"` as Boolean False\n\n`controls` has no boolean semantic. Removing arrow buttons is done with `controls=\"none\"`, not by writing `controls=\"false\"` or `disabled`. The string `\"false\"` is not a `ViewportType` and does nothing.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-horizontal-scroll controls=\"false\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n\n<!-- ✅ CORRECT -->\n<mds-horizontal-scroll controls=\"none\">\n <!-- slotted items -->\n</mds-horizontal-scroll>\n```\n\n#### Do Not Use a Raw `<div>` Scroll Container Instead\n\nReplacing `<mds-horizontal-scroll>` with a manually styled `<div style=\"overflow-x: auto\">` loses the managed arrow buttons, the dot indicator, scroll-snap wiring, and the `controls` breakpoint logic. Use the component.\n\n```html\n<!-- 🚫 INCORRECT -->\n<div style=\"overflow-x: auto; display: flex; gap: 16px;\">\n <mds-card class=\"min-w-[320px]\">...</mds-card>\n <mds-card class=\"min-w-[320px]\">...</mds-card>\n</div>\n\n<!-- ✅ CORRECT -->\n<mds-horizontal-scroll>\n <mds-card class=\"min-w-[320px]\">...</mds-card>\n <mds-card class=\"min-w-[320px]\">...</mds-card>\n</mds-horizontal-scroll>\n```\n\n#### Do Not Pierce the Shadow DOM to Style Internal Elements\n\nThe navigation buttons and dot indicator live inside the shadow DOM. Targeting them via `>>>`, `/deep/`, or undocumented class names (`.navigation`, `.dot`) will break on future releases. Use `--mds-horizontal-scroll-*` CSS custom properties instead.\n\n```css\n/* 🚫 INCORRECT */\nmds-horizontal-scroll >>> .dot {\n background: red;\n}\nmds-horizontal-scroll >>> .navigation {\n border-radius: 0;\n}\n\n/* ✅ CORRECT */\nmds-horizontal-scroll {\n --mds-horizontal-scroll-dot-background: rgb(var(--variant-primary-03));\n}\nmds-horizontal-scroll::part(content) {\n padding-block: var(--spacing-800);\n}\n```\n\n#### Do Not Provide Slotted Items Without a Fixed Width\n\nSlotted items without a declared width collapse to zero or stretch unpredictably. Always give direct children an explicit `min-width` or `width` so the container has measurable items to snap and scroll among.\n\n```html\n<!-- 🚫 INCORRECT: card has no fixed width, items will collapse -->\n<mds-horizontal-scroll>\n <mds-card>...</mds-card>\n <mds-card>...</mds-card>\n</mds-horizontal-scroll>\n\n<!-- ✅ CORRECT: each card has a declared minimum width -->\n<mds-horizontal-scroll>\n <mds-card class=\"min-w-[320px]\">...</mds-card>\n <mds-card class=\"min-w-[320px]\">...</mds-card>\n</mds-horizontal-scroll>\n```\n"
|
|
11399
11291
|
},
|
|
11400
11292
|
"props": [
|
|
@@ -11571,11 +11463,6 @@
|
|
|
11571
11463
|
"events": [],
|
|
11572
11464
|
"listeners": [],
|
|
11573
11465
|
"styles": [
|
|
11574
|
-
{
|
|
11575
|
-
"name": "--mds-horizontal-scroll-background",
|
|
11576
|
-
"annotation": "prop",
|
|
11577
|
-
"docs": "Sets the background-color of the component"
|
|
11578
|
-
},
|
|
11579
11466
|
{
|
|
11580
11467
|
"name": "--mds-horizontal-scroll-behavior",
|
|
11581
11468
|
"annotation": "prop",
|
|
@@ -11784,6 +11671,7 @@
|
|
|
11784
11671
|
"mds-help",
|
|
11785
11672
|
"mds-img",
|
|
11786
11673
|
"mds-input",
|
|
11674
|
+
"mds-input-select",
|
|
11787
11675
|
"mds-input-switch",
|
|
11788
11676
|
"mds-input-upload",
|
|
11789
11677
|
"mds-keyboard-key",
|
|
@@ -11830,6 +11718,9 @@
|
|
|
11830
11718
|
"mds-input": [
|
|
11831
11719
|
"mds-icon"
|
|
11832
11720
|
],
|
|
11721
|
+
"mds-input-select": [
|
|
11722
|
+
"mds-icon"
|
|
11723
|
+
],
|
|
11833
11724
|
"mds-input-switch": [
|
|
11834
11725
|
"mds-icon"
|
|
11835
11726
|
],
|
|
@@ -12111,10 +12002,10 @@
|
|
|
12111
12002
|
},
|
|
12112
12003
|
{
|
|
12113
12004
|
"name": "src",
|
|
12114
|
-
"type": "string",
|
|
12005
|
+
"type": "string | undefined",
|
|
12115
12006
|
"complexType": {
|
|
12116
12007
|
"original": "string",
|
|
12117
|
-
"resolved": "string",
|
|
12008
|
+
"resolved": "string | undefined",
|
|
12118
12009
|
"references": {}
|
|
12119
12010
|
},
|
|
12120
12011
|
"mutable": false,
|
|
@@ -12125,9 +12016,12 @@
|
|
|
12125
12016
|
"values": [
|
|
12126
12017
|
{
|
|
12127
12018
|
"type": "string"
|
|
12019
|
+
},
|
|
12020
|
+
{
|
|
12021
|
+
"type": "undefined"
|
|
12128
12022
|
}
|
|
12129
12023
|
],
|
|
12130
|
-
"optional":
|
|
12024
|
+
"optional": true,
|
|
12131
12025
|
"required": false,
|
|
12132
12026
|
"getter": false,
|
|
12133
12027
|
"setter": false
|
|
@@ -12211,30 +12105,7 @@
|
|
|
12211
12105
|
"setter": false
|
|
12212
12106
|
}
|
|
12213
12107
|
],
|
|
12214
|
-
"methods": [
|
|
12215
|
-
{
|
|
12216
|
-
"name": "updateLang",
|
|
12217
|
-
"returns": {
|
|
12218
|
-
"type": "Promise<void>",
|
|
12219
|
-
"docs": ""
|
|
12220
|
-
},
|
|
12221
|
-
"complexType": {
|
|
12222
|
-
"signature": "() => Promise<void>",
|
|
12223
|
-
"parameters": [],
|
|
12224
|
-
"references": {
|
|
12225
|
-
"Promise": {
|
|
12226
|
-
"location": "global",
|
|
12227
|
-
"id": "global::Promise"
|
|
12228
|
-
}
|
|
12229
|
-
},
|
|
12230
|
-
"return": "Promise<void>"
|
|
12231
|
-
},
|
|
12232
|
-
"signature": "updateLang() => Promise<void>",
|
|
12233
|
-
"parameters": [],
|
|
12234
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
12235
|
-
"docsTags": []
|
|
12236
|
-
}
|
|
12237
|
-
],
|
|
12108
|
+
"methods": [],
|
|
12238
12109
|
"events": [
|
|
12239
12110
|
{
|
|
12240
12111
|
"event": "mdsImgLoadError",
|
|
@@ -12361,10 +12232,36 @@
|
|
|
12361
12232
|
"docsTags": [],
|
|
12362
12233
|
"usage": {
|
|
12363
12234
|
"1. Description": "The `<mds-input>` web component is the primary single- and multi-line text entry control of the Magma Design System. It wraps a native `<input>` (or `<textarea>` when `type=\"textarea\"`) and layers on form association, validation, inline tips, iconography, password masking, numeric steppers, datalist suggestions and speech-to-text dictation.\n\n#### Semantic Behavior\n\n- **Form association**: The component reports its value to the surrounding `<form>`, so it submits and participates in reset natively. On `disabled` or form reset the reported value is cleared.\n- **Validation on blur**: Validation runs when the field loses focus (and re-runs on input once invalid). It drives the `variant` automatically to `'success'` or `'error'`, emits `mdsInputValidation` with the boolean result, and reverts to `'primary'` when an optional field is emptied.\n- **Type-aware validators**: The active validator set is derived from `type` - `cf`, `isbn`, `cc`, `piva` install format/mask validators, while `required`, `min`/`max` and `minlength`/`maxlength` add the corresponding constraint validators. Custom validators can be attached at runtime through the `addValidator`/`removeValidator`/`hasValidator`/`getErrors` methods.\n- **Disabled / read-only tips**: `disabled` and `readonly` surface a persistent top tip describing the state; read-only fields also auto-select their text on focus.\n- **Character counter**: When `maxlength` is set a bottom counter tip shows `current / max` and shifts through fullness variants as the value approaches the limit. A `maxlength` of `0` or less is treated as unset.\n- **Password masking**: With `type=\"password\"` a toggle button reveals/hides the value.\n- **Number steppers**: With `type=\"number\"` increment/decrement buttons are rendered; their placement follows `controlsLayout` and their glyphs follow `controlsIcon`.\n- **Speech-to-text**: When `mic` is set a dictation button transcribes speech into the value, emitting `mdsInputSpeechEnd` when recognition stops; it degrades gracefully when unavailable.\n- **Emitted events**: `mdsInputChange` carries the new value, `mdsInputKeydown` forwards input keystrokes, and `mdsInputFocus`/`mdsInputBlur` fire on focus transitions.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` ladder (color role) is defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); `<mds-input>` consumes it for both intent styling and validation feedback, but does not expose a `tone` prop. It uses the full shared set and adds no component-specific variants.\n\n- **`type`** selects both the rendered control and the validation profile: it covers the native HTML types plus Italian-specific masked formats (`'cf'`, `'piva'`, `'isbn'`, `'cc'`) and switches the host to a multi-line `<textarea>` for `'textarea'`.\n- **`variant=\"ai\"`** auto-assigns the AI chatbot icon when no `icon` is otherwise provided, signposting AI-assisted fields.\n\n#### Other behavioral props\n\n- **`icon`** is an SVG filename slug from the Magma icon library shown at the trailing edge of the field; it is suppressed while `await` is active, since the spinner takes its place.\n- **`controlsLayout`** chooses between stacked (`'vertical'`) and split (`'horizontal'`) stepper buttons, and **`controlsIcon`** picks arrow vs. plus/minus glyphs - both apply only to `type=\"number\"`.\n- **`datalist`** supplies suggestion options for `type=\"search\"` style autocompletion.\n- **`tip`** renders inline helper text below the field, and **`typography`** selects the field's text scale.\n",
|
|
12364
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-input>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Text Input\n\nThe simplest form: set `name` for form participation and `placeholder` for a visual hint. Wrap the component in [`mds-input-field`](../../mds-input-field) to add a visible label and associated tip.\n\n```html\n<mds-input\n name=\"cognome\"\n placeholder=\"Inserisci il tuo cognome\"\n></mds-input>\n```\n\n#### Required Field with `tip` Helper Text\n\nUse `required` to enforce non-empty submission and `tip` to explain the constraint. The component surfaces a top-tip when focused and drives `variant` to `'error'` or `'success'` on blur.\n\n```html\n<mds-input\n name=\"email\"\n type=\"email\"\n placeholder=\"nome@esempio.it\"\n required\n tip=\"Inserisci un indirizzo email valido\"\n></mds-input>\n```\n\n#### Textarea for Multi-line Content\n\nSet `type=\"textarea\"` to render a `<textarea>` instead of a single-line `<input>`. Use the `--mds-input-textarea-*` custom properties to control height and resize behaviour.\n\n```html\n<mds-input\n name=\"descrizione\"\n type=\"textarea\"\n placeholder=\"Descrivi il problema...\"\n maxlength=\"500\"\n></mds-input>\n```\n\n#### Character Counter via `maxlength`\n\nWhen `maxlength` is set the component renders a live `current / max` counter below the field. The counter shifts through fullness variants as the limit approaches. A value of `0` or less is treated as unset.\n\n```html\n<mds-input\n name=\"titolo\"\n placeholder=\"Titolo dell'articolo\"\n maxlength=\"120\"\n></mds-input>\n```\n\n#### Numeric Input with Steppers\n\nSet `type=\"number\"` to enable built-in increment/decrement buttons. Use `controlsLayout` to choose between stacked (`'vertical'`, default) and split (`'horizontal'`) placement, and `controlsIcon` to pick arrow vs. plus/minus glyphs. Use `min`, `max`, and `step` to constrain the legal range.\n\n```html\n<!-- Stacked (default) - arrow glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"1\"\n max=\"99\"\n step=\"1\"\n placeholder=\"1\"\n></mds-input>\n\n<!-- Horizontal split - arithmetic glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"0\"\n max=\"100\"\n controls-layout=\"horizontal\"\n controls-icon=\"arithmetic\"\n placeholder=\"0\"\n></mds-input>\n```\n\n#### Password Input\n\nSet `type=\"password\"` to render a masked field with a built-in visibility toggle. The component renders a custom dot-mask overlay and a show/hide button - no extra wiring is needed.\n\n```html\n<mds-input\n name=\"password\"\n type=\"password\"\n placeholder=\"Scegli una password\"\n required\n></mds-input>\n```\n\n#### Italian-Specific Masked Types\n\n`type=\"cf\"`, `type=\"piva\"`, `type=\"cc\"`, and `type=\"isbn\"` install a format-aware validator and apply the appropriate keyboard mask. Use them whenever a masked format is expected.\n\n```html\n<mds-input name=\"codice_fiscale\" type=\"cf\" placeholder=\"RSSMRA80A01H501Z\"></mds-input>\n<mds-input name=\"partita_iva\" type=\"piva\" placeholder=\"01234567890\"></mds-input>\n```\n\n#### Search Input with Datalist\n\nUse `type=\"search\"` combined with the `datalist` prop to offer autocomplete suggestions from a fixed list. The list is rendered inside the shadow DOM and wired automatically.\n\n```html\n<mds-input\n name=\"comune\"\n type=\"search\"\n placeholder=\"Cerca comune...\"\n></mds-input>\n```\n\n```javascript\n// Pass suggestions as a JavaScript array\ndocument.querySelector('mds-input').datalist = ['Roma', 'Milano', 'Napoli', 'Torino'];\n```\n\n#### Icon Decoration\n\nThe `icon` prop renders an SVG slug from the Magma icon library at the leading edge of the field. The icon is suppressed while `await` is active and the spinner takes its place.\n\n```html\n<mds-input\n name=\"cerca\"\n type=\"search\"\n icon=\"mi/baseline/search\"\n placeholder=\"Cerca...\"\n></mds-input>\n```\n\n#### AI-Assisted Field\n\nSet `variant=\"ai\"` to signal an AI-powered field. When no `icon` prop is present, the component auto-assigns the AI chatbot icon.\n\n```html\n<mds-input\n name=\"prompt\"\n type=\"text\"\n variant=\"ai\"\n placeholder=\"Chiedi qualcosa all'assistente...\"\n></mds-input>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while an async operation (e.g. a lookup) is in flight. The component renders an inline spinner in place of the icon. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-input name=\"codice\" placeholder=\"Verifica in corso...\" await></mds-input>\n```\n\n#### Speech-to-Text Dictation\n\nSet the `mic` boolean attribute to render a dictation button. The component appends recognized speech to the current value and emits `mdsInputSpeechEnd` when recognition stops. It degrades gracefully if the Web Speech API is unavailable.\n\n```html\n<mds-input\n name=\"note_vocali\"\n type=\"text\"\n mic\n placeholder=\"Parla o scrivi...\"\n></mds-input>\n```\n\n#### Listening to Events\n\nListen for `mdsInputChange` instead of native `input` or `change` - these native events may not bubble out of the shadow DOM reliably.\n\n```javascript\ndocument.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {\n console.log(e.detail.value);\n});\n\ndocument.querySelector('mds-input').addEventListener('mdsInputValidation', (e) => {\n console.log('valido:', e.detail);\n});\n```\n\n#### Form Participation\n\n`<mds-input>` is form-associated. It submits, resets, and validates natively inside a `<form>`. Set `name` so the value is included in form data.\n\n```html\n<form action=\"/salva\" method=\"post\">\n <mds-input name=\"nome\" type=\"text\" placeholder=\"Nome\" required></mds-input>\n <mds-input name=\"cognome\" type=\"text\" placeholder=\"Cognome\" required></mds-input>\n <mds-input name=\"email\" type=\"email\" placeholder=\"Email\" required></mds-input>\n\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n</form>\n```\n\n#### Read-Only Display\n\nUse `readonly` when the value should be visible but not editable. A top tip describes the state on focus, and the field text is auto-selected on click for easy copying.\n\n```html\n<mds-input\n name=\"codice_riferimento\"\n value=\"REF-2024-00123\"\n readonly\n></mds-input>\n```\n\n#### Styling Customization\n\nStyle the input only through its documented `--mds-input-*` CSS custom properties. Set them on the host or a parent selector. Use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.search-bar mds-input {\n --mds-input-background: rgb(var(--tone-neutral-09));\n --mds-input-placeholder-default-color: rgb(var(--tone-neutral-05));\n --mds-input-icon-color: rgb(var(--variant-primary-03));\n}\n\n/* Textarea: fixed height, allow resize */\n.notes-area mds-input {\n --mds-input-textarea-min-height: 8rem;\n --mds-input-textarea-max-height: 24rem;\n --mds-input-textarea-resize: vertical;\n}\n```\n",
|
|
12235
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-input>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Text Input\n\nThe simplest form: set `name` for form participation and `placeholder` for a visual hint. Wrap the component in [`mds-input-field`](../../mds-input-field) to add a visible label and associated tip.\n\n```html\n<mds-input\n name=\"cognome\"\n placeholder=\"Inserisci il tuo cognome\"\n></mds-input>\n```\n\n#### Required Field with `tip` Helper Text\n\nUse `required` to enforce non-empty submission and `tip` to explain the constraint. The component surfaces a top-tip when focused and drives `variant` to `'error'` or `'success'` on blur. When the field collects the user's own data, set the matching `autocomplete` token (`email`, `given-name`, `tel`, ...) so browsers can identify its purpose (WCAG 2.1 SC 1.3.5) and offer autofill; without it the component default `autocomplete=\"off\"` applies.\n\n```html\n<mds-input\n name=\"email\"\n type=\"email\"\n autocomplete=\"email\"\n placeholder=\"nome@esempio.it\"\n required\n tip=\"Inserisci un indirizzo email valido\"\n></mds-input>\n```\n\n#### Textarea for Multi-line Content\n\nSet `type=\"textarea\"` to render a `<textarea>` instead of a single-line `<input>`. Use the `--mds-input-textarea-*` custom properties to control height and resize behaviour.\n\n```html\n<mds-input\n name=\"descrizione\"\n type=\"textarea\"\n placeholder=\"Descrivi il problema...\"\n maxlength=\"500\"\n></mds-input>\n```\n\n#### Character Counter via `maxlength`\n\nWhen `maxlength` is set the component renders a live `current / max` counter below the field. The counter shifts through fullness variants as the limit approaches. A value of `0` or less is treated as unset.\n\n```html\n<mds-input\n name=\"titolo\"\n placeholder=\"Titolo dell'articolo\"\n maxlength=\"120\"\n></mds-input>\n```\n\n#### Numeric Input with Steppers\n\nSet `type=\"number\"` to enable built-in increment/decrement buttons. Use `controlsLayout` to choose between stacked (`'vertical'`, default) and split (`'horizontal'`) placement, and `controlsIcon` to pick arrow vs. plus/minus glyphs. Use `min`, `max`, and `step` to constrain the legal range.\n\n```html\n<!-- Stacked (default) - arrow glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"1\"\n max=\"99\"\n step=\"1\"\n placeholder=\"1\"\n></mds-input>\n\n<!-- Horizontal split - arithmetic glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"0\"\n max=\"100\"\n controls-layout=\"horizontal\"\n controls-icon=\"arithmetic\"\n placeholder=\"0\"\n></mds-input>\n```\n\n#### Password Input\n\nSet `type=\"password\"` to render a masked field with a built-in visibility toggle. The component renders a custom dot-mask overlay and a show/hide button - no extra wiring is needed. Always set `autocomplete` to `new-password` (sign-up, password change) or `current-password` (login): the component default is `autocomplete=\"off\"`, which browsers and password managers ignore on credential fields, but the explicit token is what lets them pair the password with its username field and fill or generate the right value.\n\n```html\n<mds-input\n name=\"password\"\n type=\"password\"\n autocomplete=\"new-password\"\n placeholder=\"Scegli una password\"\n required\n></mds-input>\n```\n\n#### Login Form\n\nPair a username field carrying `autocomplete=\"username\"` with a password field carrying `autocomplete=\"current-password\"` inside a `<form>`, and submit through `<mds-button type=\"submit\">`. The native fields live in the Shadow DOM of each `<mds-input>`: among the password managers tested, Bitwarden, LastPass, Chrome and Edge detect and fill them, Firefox's built-in manager and KeePassXC-Browser do not (they only look at the light DOM).\n\n```html\n<form action=\"/login\" method=\"post\">\n <mds-input-field label=\"Email\">\n <mds-input name=\"username\" type=\"email\" autocomplete=\"username\" required></mds-input>\n </mds-input-field>\n <mds-input-field label=\"Password\">\n <mds-input name=\"password\" type=\"password\" autocomplete=\"current-password\" required></mds-input>\n </mds-input-field>\n\n <mds-button type=\"submit\" label=\"Accedi\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Italian-Specific Masked Types\n\n`type=\"cf\"`, `type=\"piva\"`, `type=\"cc\"`, and `type=\"isbn\"` install a format-aware validator and apply the appropriate keyboard mask. Use them whenever a masked format is expected.\n\n```html\n<mds-input name=\"codice_fiscale\" type=\"cf\" placeholder=\"RSSMRA80A01H501Z\"></mds-input>\n<mds-input name=\"partita_iva\" type=\"piva\" placeholder=\"01234567890\"></mds-input>\n```\n\n#### Search Input with Datalist\n\nUse `type=\"search\"` combined with the `datalist` prop to offer autocomplete suggestions from a fixed list. The list is rendered inside the shadow DOM and wired automatically.\n\n```html\n<mds-input\n name=\"comune\"\n type=\"search\"\n placeholder=\"Cerca comune...\"\n></mds-input>\n```\n\n```javascript\n// Pass suggestions as a JavaScript array\ndocument.querySelector('mds-input').datalist = ['Roma', 'Milano', 'Napoli', 'Torino'];\n```\n\n#### Icon Decoration\n\nThe `icon` prop renders an SVG slug from the Magma icon library at the leading edge of the field. The icon is suppressed while `await` is active and the spinner takes its place.\n\n```html\n<mds-input\n name=\"cerca\"\n type=\"search\"\n icon=\"mi/baseline/search\"\n placeholder=\"Cerca...\"\n></mds-input>\n```\n\n#### AI-Assisted Field\n\nSet `variant=\"ai\"` to signal an AI-powered field. When no `icon` prop is present, the component auto-assigns the AI chatbot icon.\n\n```html\n<mds-input\n name=\"prompt\"\n type=\"text\"\n variant=\"ai\"\n placeholder=\"Chiedi qualcosa all'assistente...\"\n></mds-input>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while an async operation (e.g. a lookup) is in flight. The component renders an inline spinner in place of the icon. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-input name=\"codice\" placeholder=\"Verifica in corso...\" await></mds-input>\n```\n\n#### Speech-to-Text Dictation\n\nSet the `mic` boolean attribute to render a dictation button. The component appends recognized speech to the current value and emits `mdsInputSpeechEnd` when recognition stops. It degrades gracefully if the Web Speech API is unavailable.\n\n```html\n<mds-input\n name=\"note_vocali\"\n type=\"text\"\n mic\n placeholder=\"Parla o scrivi...\"\n></mds-input>\n```\n\n#### Listening to Events\n\nListen for `mdsInputChange` instead of native `input` or `change` - these native events may not bubble out of the shadow DOM reliably.\n\n```javascript\ndocument.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {\n console.log(e.detail.value);\n});\n\ndocument.querySelector('mds-input').addEventListener('mdsInputValidation', (e) => {\n console.log('valido:', e.detail);\n});\n```\n\n#### Form Participation\n\n`<mds-input>` is form-associated. It submits, resets, and validates natively inside a `<form>`. Set `name` so the value is included in form data.\n\n```html\n<form action=\"/salva\" method=\"post\">\n <mds-input name=\"nome\" type=\"text\" placeholder=\"Nome\" required></mds-input>\n <mds-input name=\"cognome\" type=\"text\" placeholder=\"Cognome\" required></mds-input>\n <mds-input name=\"email\" type=\"email\" placeholder=\"Email\" required></mds-input>\n\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n</form>\n```\n\n#### Read-Only Display\n\nUse `readonly` when the value should be visible but not editable. A top tip describes the state on focus, and the field text is auto-selected on click for easy copying.\n\n```html\n<mds-input\n name=\"codice_riferimento\"\n value=\"REF-2024-00123\"\n readonly\n></mds-input>\n```\n\n#### Styling Customization\n\nStyle the input only through its documented `--mds-input-*` CSS custom properties. Set them on the host or a parent selector. Use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.search-bar mds-input {\n --mds-input-background: rgb(var(--tone-neutral-09));\n --mds-input-placeholder-default-color: rgb(var(--tone-neutral-05));\n --mds-input-icon-color: rgb(var(--variant-primary-03));\n}\n\n/* Textarea: fixed height, allow resize */\n.notes-area mds-input {\n --mds-input-textarea-min-height: 8rem;\n --mds-input-textarea-max-height: 24rem;\n --mds-input-textarea-resize: vertical;\n}\n```\n",
|
|
12365
12236
|
"3. Antipattern": "Common incorrect uses of `<mds-input>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use a Raw `<input>` When `<mds-input>` Exists\n\nReaching for a plain `<input>` bypasses theming, validation, tips, accessible state announcements, and form-reset behavior provided by the component.\n\n```html\n<!-- 🚫 INCORRECT -->\n<input type=\"text\" name=\"nome\" placeholder=\"Nome\" class=\"my-input\">\n\n<!-- ✅ CORRECT -->\n<mds-input name=\"nome\" type=\"text\" placeholder=\"Nome\"></mds-input>\n```\n\n#### Do Not Set Boolean Attributes to the String `\"false\"`\n\n`disabled=\"false\"`, `required=\"false\"`, `readonly=\"false\"`, `mic=\"false\"`, and `await=\"false\"` are all truthy in HTML - any non-empty string activates the attribute. Remove the attribute entirely to turn it off.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input name=\"note\" disabled=\"false\" required=\"false\"></mds-input>\n\n<!-- ✅ CORRECT -->\n<mds-input name=\"note\"></mds-input>\n```\n\n#### Do Not Force `variant` for Validation Feedback\n\nThe component drives `variant` to `'success'` or `'error'` automatically on blur when validators are active. Setting `variant` manually overrides the feedback and breaks the visual contract.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input name=\"codice\" variant=\"error\" tip=\"Valore non valido\"></mds-input>\n\n<!-- ✅ CORRECT -->\n<mds-input name=\"codice\" required tip=\"Inserisci un valore valido\"></mds-input>\n```\n\n#### Do Not Listen to Native `input` or `change` Events\n\nNative DOM events may not bubble out of the shadow root reliably. Use the documented `mdsInputChange` event instead.\n\n```javascript\n// 🚫 INCORRECT\ndocument.querySelector('mds-input').addEventListener('input', (e) => {\n console.log(e.target.value);\n});\n\n// ✅ CORRECT\ndocument.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {\n console.log(e.detail.value);\n});\n```\n\n#### Do Not Use `type=\"number\"` Native Browser Spinners and Then Override the Input\n\nThe component renders its own increment/decrement buttons and hides the native browser spinners. Do not try to re-enable them via CSS, and do not add inline JS `stepUp`/`stepDown` calls - use the `controlsLayout` and `controlsIcon` props to configure the built-in controls.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input type=\"number\" style=\"-moz-appearance: auto;\"></mds-input>\n\n<!-- ✅ CORRECT -->\n<mds-input\n type=\"number\"\n controls-layout=\"horizontal\"\n controls-icon=\"arithmetic\"\n min=\"0\"\n max=\"100\"\n></mds-input>\n```\n\n#### Do Not Use a Legacy or Invalid `type` Value\n\n`<mds-input>` accepts a specific set of `type` values: `text`, `email`, `number`, `password`, `search`, `tel`, `url`, `date`, `time`, `textarea`, `cf`, `piva`, `cc`, `isbn`. Supplying anything else (e.g. `\"checkbox\"`, `\"radio\"`, `\"file\"`) silently falls back to `text` behavior and ignores the type-specific logic. Use the dedicated Magma component for those controls.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input type=\"checkbox\" name=\"accetto\"></mds-input>\n<mds-input type=\"file\" name=\"allegato\"></mds-input>\n\n<!-- ✅ CORRECT -->\n<mds-input-switch name=\"accetto\"></mds-input-switch>\n<mds-input-upload name=\"allegato\"></mds-input-upload>\n```\n\n#### Do Not Use `placeholder` as the Accessible Label\n\n`placeholder` disappears on input and is never read as a label by assistive tech. Always pair `<mds-input>` with [`mds-input-field`](../../mds-input-field) (which provides the visible `<label>` association) or supply `aria-label` directly on the host.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input name=\"ricerca\" placeholder=\"Cerca per nome\"></mds-input>\n\n<!-- ✅ CORRECT -->\n<mds-input-field label=\"Cerca per nome\">\n <mds-input name=\"ricerca\" placeholder=\"Cerca per nome\"></mds-input>\n</mds-input-field>\n```\n\n#### Do Not Pierce the Shadow DOM to Style Internal Parts\n\nThe supported customization surface is `--mds-input-*` CSS custom properties plus the documented shadow parts (`field`, `tip-top`, `tip-bottom`, `tip-count`, `password-toggle-button`, `counter-button-increase`, `counter-button-decrease`, `mic-toggle-button`). Targeting undocumented internals via `>>>` or arbitrary class names couples your code to the Shadow DOM implementation.\n\n```css\n/* 🚫 INCORRECT */\nmds-input >>> .input {\n border: 2px solid red;\n}\n\n/* ✅ CORRECT */\nmds-input {\n --mds-input-ring: 0 0 0 2px rgb(var(--status-error-05));\n --mds-input-background: rgb(var(--status-error-09));\n}\nmds-input::part(field) {\n font-style: italic;\n}\n```\n"
|
|
12366
12237
|
},
|
|
12367
12238
|
"props": [
|
|
12239
|
+
{
|
|
12240
|
+
"name": "accessibleName",
|
|
12241
|
+
"type": "string | undefined",
|
|
12242
|
+
"complexType": {
|
|
12243
|
+
"original": "string",
|
|
12244
|
+
"resolved": "string | undefined",
|
|
12245
|
+
"references": {}
|
|
12246
|
+
},
|
|
12247
|
+
"mutable": false,
|
|
12248
|
+
"attr": "aria-label",
|
|
12249
|
+
"reflectToAttr": false,
|
|
12250
|
+
"docs": "The accessible name of the native control: the label a screen reader announces. An\n`mds-input-field` around the component passes its own label down here, so the attribute\nis only written by hand when the input stands on its own. The placeholder is deliberately\nnot a fallback: it disappears as soon as the field is filled.",
|
|
12251
|
+
"docsTags": [],
|
|
12252
|
+
"values": [
|
|
12253
|
+
{
|
|
12254
|
+
"type": "string"
|
|
12255
|
+
},
|
|
12256
|
+
{
|
|
12257
|
+
"type": "undefined"
|
|
12258
|
+
}
|
|
12259
|
+
],
|
|
12260
|
+
"optional": true,
|
|
12261
|
+
"required": false,
|
|
12262
|
+
"getter": false,
|
|
12263
|
+
"setter": false
|
|
12264
|
+
},
|
|
12368
12265
|
{
|
|
12369
12266
|
"name": "autocomplete",
|
|
12370
12267
|
"type": "\"additional-name\" | \"address\" | \"address-level1\" | \"address-level2\" | \"address-level3\" | \"address-level4\" | \"address-line1\" | \"address-line2\" | \"address-line3\" | \"bday\" | \"bday-day\" | \"bday-month\" | \"bday-year\" | \"cc-additional-name\" | \"cc-csc\" | \"cc-exp\" | \"cc-exp-month\" | \"cc-exp-year\" | \"cc-family-name\" | \"cc-given-name\" | \"cc-name\" | \"cc-number\" | \"cc-type\" | \"country\" | \"country-name\" | \"current-password\" | \"email\" | \"family-name\" | \"given-name\" | \"honorific-prefix\" | \"honorific-suffix\" | \"impp\" | \"language\" | \"name\" | \"new-password\" | \"nickname\" | \"off\" | \"on\" | \"one-time-code\" | \"organization\" | \"organization-title\" | \"photo\" | \"postal-code\" | \"sex\" | \"street-address\" | \"tel\" | \"tel-area-code\" | \"tel-country-code\" | \"tel-extension\" | \"tel-local\" | \"tel-national\" | \"transaction-amount\" | \"transaction-currency\" | \"url\" | \"username\" | undefined",
|
|
@@ -13627,28 +13524,6 @@
|
|
|
13627
13524
|
"parameters": [],
|
|
13628
13525
|
"docs": "Sets focus on the specified `my-input`.\nUse this method instead\nof the global `input.focus()`.",
|
|
13629
13526
|
"docsTags": []
|
|
13630
|
-
},
|
|
13631
|
-
{
|
|
13632
|
-
"name": "updateLang",
|
|
13633
|
-
"returns": {
|
|
13634
|
-
"type": "Promise<void>",
|
|
13635
|
-
"docs": ""
|
|
13636
|
-
},
|
|
13637
|
-
"complexType": {
|
|
13638
|
-
"signature": "() => Promise<void>",
|
|
13639
|
-
"parameters": [],
|
|
13640
|
-
"references": {
|
|
13641
|
-
"Promise": {
|
|
13642
|
-
"location": "global",
|
|
13643
|
-
"id": "global::Promise"
|
|
13644
|
-
}
|
|
13645
|
-
},
|
|
13646
|
-
"return": "Promise<void>"
|
|
13647
|
-
},
|
|
13648
|
-
"signature": "updateLang() => Promise<void>",
|
|
13649
|
-
"parameters": [],
|
|
13650
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
13651
|
-
"docsTags": []
|
|
13652
13527
|
}
|
|
13653
13528
|
],
|
|
13654
13529
|
"events": [
|
|
@@ -13920,6 +13795,32 @@
|
|
|
13920
13795
|
"3. Antipattern": "Common incorrect uses of `<mds-input-date>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use Non-ISO Date Strings\n\n`value`, `min`, and `max` must be ISO 8601 date strings (`YYYY-MM-DD`). Any other format is passed to `DateTime.fromISO`, which marks the date invalid and immediately trips validation.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input-date value=\"31/12/2026\" max=\"31-12-2026\"></mds-input-date>\n\n<!-- ✅ CORRECT -->\n<mds-input-date value=\"2026-12-31\" max=\"2026-12-31\"></mds-input-date>\n```\n\n#### Do Not Hardcode `variant=\"error\"` to Signal Validation\n\nThe component manages `variant` automatically: it sets `'error'` when validation fails and restores `'primary'` when it passes. Hardcoding `variant=\"error\"` is overwritten on the first user interaction and does not persist.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input-date name=\"dataScadenza\" variant=\"error\"></mds-input-date>\n\n<!-- ✅ CORRECT - let validation drive variant; listen to mdsInputValidation instead -->\n<mds-input-date name=\"dataScadenza\" required></mds-input-date>\n```\n\n#### Do Not Listen to the Native `change` or `input` Events\n\nThe component emits `mdsInputDateSelect` (value string) and `mdsInputValidation` (boolean). Listening to native `change` or `input` may not bubble reliably through Shadow DOM and will miss calendar-driven picks.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input-date id=\"picker\" name=\"data\"></mds-input-date>\n<script>\n document.getElementById('picker').addEventListener('change', handler);\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-input-date id=\"picker\" name=\"data\"></mds-input-date>\n<script>\n document.getElementById('picker').addEventListener('mdsInputDateSelect', handler);\n</script>\n```\n\n#### Do Not Use a Raw `<input type=\"date\">` as a Drop-in Replacement\n\nReplacing `<mds-input-date>` with a plain `<input type=\"date\">` loses form-association conventions, theming, the calendar overlay, the contextual tip, and all Magma accessibility defaults.\n\n```html\n<!-- 🚫 INCORRECT -->\n<input type=\"date\" name=\"dataEvento\" />\n\n<!-- ✅ CORRECT -->\n<mds-input-date name=\"dataEvento\"></mds-input-date>\n```\n\n#### Do Not Set `disabled=\"false\"` or `readonly=\"false\"` to Remove the State\n\nBoolean attributes must be absent to be off. Setting them to the string `\"false\"` is truthy in HTML and keeps the state active.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input-date name=\"data\" disabled=\"false\" readonly=\"false\"></mds-input-date>\n\n<!-- ✅ CORRECT - remove the attribute entirely -->\n<mds-input-date name=\"data\"></mds-input-date>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Inner Input\n\nThe documented customization surface is `--mds-input-date-*` CSS custom properties plus the `::part(input-date)` part. Targeting internals with `>>>`, `/deep/`, or undocumented selectors will break on any minor release.\n\n```css\n/* 🚫 INCORRECT */\nmds-input-date >>> .input {\n border: 2px solid red;\n}\n\n/* ✅ CORRECT */\nmds-input-date {\n --mds-input-date-ring: 0 0 0 2px rgb(var(--status-error-04) / 0.8);\n}\nmds-input-date::part(input-date) {\n font-size: var(--font-size-sm);\n}\n```\n\n#### Do Not Set `value` to Clear the Field\n\nSetting `value=\"\"` is the correct way to clear; do not set `value` to a non-ISO string expecting the component to silently ignore it - it passes through validation and trips an error state.\n\n```html\n<!-- 🚫 INCORRECT (non-ISO value to \"reset\") -->\n<mds-input-date name=\"data\" value=\"clear\"></mds-input-date>\n\n<!-- ✅ CORRECT -->\n<mds-input-date name=\"data\" value=\"\"></mds-input-date>\n```\n"
|
|
13921
13796
|
},
|
|
13922
13797
|
"props": [
|
|
13798
|
+
{
|
|
13799
|
+
"name": "accessibleName",
|
|
13800
|
+
"type": "string | undefined",
|
|
13801
|
+
"complexType": {
|
|
13802
|
+
"original": "string",
|
|
13803
|
+
"resolved": "string | undefined",
|
|
13804
|
+
"references": {}
|
|
13805
|
+
},
|
|
13806
|
+
"mutable": false,
|
|
13807
|
+
"attr": "aria-label",
|
|
13808
|
+
"reflectToAttr": false,
|
|
13809
|
+
"docs": "The accessible name of the native control: the label a screen reader announces. An\n`mds-input-field` around the component passes its own label down here, so the attribute\nis only written by hand when the control stands on its own. The placeholder is deliberately\nnot a fallback: it disappears as soon as the field is filled.",
|
|
13810
|
+
"docsTags": [],
|
|
13811
|
+
"values": [
|
|
13812
|
+
{
|
|
13813
|
+
"type": "string"
|
|
13814
|
+
},
|
|
13815
|
+
{
|
|
13816
|
+
"type": "undefined"
|
|
13817
|
+
}
|
|
13818
|
+
],
|
|
13819
|
+
"optional": true,
|
|
13820
|
+
"required": false,
|
|
13821
|
+
"getter": false,
|
|
13822
|
+
"setter": false
|
|
13823
|
+
},
|
|
13923
13824
|
{
|
|
13924
13825
|
"name": "delay",
|
|
13925
13826
|
"type": "number",
|
|
@@ -13985,6 +13886,35 @@
|
|
|
13985
13886
|
"getter": false,
|
|
13986
13887
|
"setter": false
|
|
13987
13888
|
},
|
|
13889
|
+
{
|
|
13890
|
+
"name": "hideToday",
|
|
13891
|
+
"type": "boolean",
|
|
13892
|
+
"complexType": {
|
|
13893
|
+
"original": "boolean",
|
|
13894
|
+
"resolved": "boolean",
|
|
13895
|
+
"references": {}
|
|
13896
|
+
},
|
|
13897
|
+
"mutable": false,
|
|
13898
|
+
"attr": "hide-today",
|
|
13899
|
+
"reflectToAttr": true,
|
|
13900
|
+
"docs": "Hides the highlight on today's date in the calendar.",
|
|
13901
|
+
"docsTags": [
|
|
13902
|
+
{
|
|
13903
|
+
"name": "default",
|
|
13904
|
+
"text": "false"
|
|
13905
|
+
}
|
|
13906
|
+
],
|
|
13907
|
+
"default": "false",
|
|
13908
|
+
"values": [
|
|
13909
|
+
{
|
|
13910
|
+
"type": "boolean"
|
|
13911
|
+
}
|
|
13912
|
+
],
|
|
13913
|
+
"optional": false,
|
|
13914
|
+
"required": false,
|
|
13915
|
+
"getter": false,
|
|
13916
|
+
"setter": false
|
|
13917
|
+
},
|
|
13988
13918
|
{
|
|
13989
13919
|
"name": "max",
|
|
13990
13920
|
"type": "null | string",
|
|
@@ -14339,31 +14269,9 @@
|
|
|
14339
14269
|
"text": "value the value to set, in ISO format (YYYY-MM-DD)"
|
|
14340
14270
|
}
|
|
14341
14271
|
]
|
|
14342
|
-
}
|
|
14343
|
-
|
|
14344
|
-
|
|
14345
|
-
"returns": {
|
|
14346
|
-
"type": "Promise<void>",
|
|
14347
|
-
"docs": ""
|
|
14348
|
-
},
|
|
14349
|
-
"complexType": {
|
|
14350
|
-
"signature": "() => Promise<void>",
|
|
14351
|
-
"parameters": [],
|
|
14352
|
-
"references": {
|
|
14353
|
-
"Promise": {
|
|
14354
|
-
"location": "global",
|
|
14355
|
-
"id": "global::Promise"
|
|
14356
|
-
}
|
|
14357
|
-
},
|
|
14358
|
-
"return": "Promise<void>"
|
|
14359
|
-
},
|
|
14360
|
-
"signature": "updateLang() => Promise<void>",
|
|
14361
|
-
"parameters": [],
|
|
14362
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
14363
|
-
"docsTags": []
|
|
14364
|
-
}
|
|
14365
|
-
],
|
|
14366
|
-
"events": [
|
|
14272
|
+
}
|
|
14273
|
+
],
|
|
14274
|
+
"events": [
|
|
14367
14275
|
{
|
|
14368
14276
|
"event": "mdsInputDateSelect",
|
|
14369
14277
|
"detail": "string",
|
|
@@ -14518,11 +14426,37 @@
|
|
|
14518
14426
|
}
|
|
14519
14427
|
],
|
|
14520
14428
|
"usage": {
|
|
14521
|
-
"1. Description": "The `<mds-input-date-range>` web component is the Magma Design System control for capturing a start/end date pair, composing two slotted `<mds-input-date>` fields with a shared pop-up `mds-calendar` (in range
|
|
14429
|
+
"1. Description": "The `<mds-input-date-range>` web component is the Magma Design System control for capturing a start/end date pair, composing two slotted `<mds-input-date>` fields with a shared pop-up `mds-calendar` (in range mode) and optional quick-pick presets. It is a form-associated compound parent that orchestrates its children rather than rendering its own native inputs.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects exactly two `<mds-input-date>` children assigned to the `start` and `end` named slots; the host keeps both in sync as a single range - it is not meant to be used with a default (text) slot.\n- **Form association**: The submitted value is a JSON string `{ startDate, endDate }`; an empty range submits no value. On form reset it restores the start/end dates present at first load.\n- **Range coercion**: When both dates are valid and the end falls before the start, the end is snapped to equal the start, so the committed range is never inverted.\n- **Min/max guard**: If `max` is earlier than `min` at load, `max` is clamped up to `min`; both bounds are forwarded to the calendar to block out-of-range selection.\n- **Commit on blur**: Leaving the component validates the range, syncs the form value, and - when both dates are valid - emits selection.\n- **Calendar selection**: Picking a complete range in the pop-up calendar emits selection and, unless `delay` is `0`, auto-closes the dropdown after the delay.\n- **Preselection sync**: Slotted `mds-input-date-range-preselection` children act as quick-picks; activating one applies its range, and any external/calendar change re-evaluates which preset (if any) is marked selected.\n- **Emitted events**: `mdsInputDateRangeValueChange` fires when a full, valid range is committed (calendar pick or focus-out with two valid dates) and either bound actually changed since the last emit.\n- **Focus management**: Clicking the host or either field label focuses the corresponding date input; a built-in calendar icon button toggles the calendar dropdown.\n- **Localization**: The \"from\"/\"to\" field labels and the calendar honor the resolved language (el/en/es/it).\n\n#### Properties & Visual Configurations\n\n- **`startDate` / `endDate`** are the controlled range bounds in ISO `YYYY-MM-DD` form; changing them externally re-syncs the slotted inputs and the calendar.\n- **`min` / `max`** define the selectable window and are enforced both in the calendar and via the coercion rules above.\n- **`delay`** is the auto-close grace period (ms) after a complete selection; set it to `0` to keep the calendar open until the user dismisses it manually.\n",
|
|
14522
14430
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-input-date-range>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the slot conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Minimal Range Picker\n\nThe canonical form. Slot one [`mds-input-date`](../../mds-input-date) as `start` and another as `end`; the host wires them together, drives the shared calendar, and handles range validation automatically.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Pre-filling the Range\n\nUse the `start-date` and `end-date` attributes to set an initial selection. Both expect ISO `YYYY-MM-DD` strings. Changing them later re-syncs the slotted inputs and the calendar automatically.\n\n```html\n<mds-input-date-range start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Constraining the Selectable Window\n\nUse `min` and `max` to block out-of-window dates in both the text inputs and the calendar. Both are ISO `YYYY-MM-DD` strings.\n\n```html\n<mds-input-date-range min=\"2026-01-01\" max=\"2026-12-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Listening to Range Events\n\n`mdsInputDateRangeValueChange` fires when a full, valid range is committed (calendar pick or focus-out with two valid dates) and either bound actually changed since the last emit. It delivers `{ startDate, endDate }` in `event.detail`.\n\n```html\n<mds-input-date-range id=\"periodo\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<script>\n document.querySelector('#periodo').addEventListener('mdsInputDateRangeValueChange', (e) => {\n console.log('Intervallo selezionato:', e.detail.startDate, '-', e.detail.endDate);\n });\n</script>\n```\n\n#### Form Participation\n\n`<mds-input-date-range>` is form-associated. Add `name` and place it inside a `<form>`; the submitted value is a JSON string `{ startDate, endDate }`. An empty range submits no value. Form reset restores the dates set at first load.\n\n```html\n<form action=\"/filtra\" method=\"get\">\n <mds-input-date-range name=\"periodo\" start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n </mds-input-date-range>\n <mds-button type=\"submit\" label=\"Applica filtro\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Reimposta\" variant=\"dark\" tone=\"outline\"></mds-button>\n</form>\n```\n\n#### Quick-Pick Preselections\n\nSlot one or more [`mds-input-date-range-preselection`](../../mds-input-date-range-preselection) elements into the component. They appear inside the calendar dropdown and act as one-click range shortcuts. The host marks the matching preset as selected whenever the current range matches.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n <mds-input-date-range-preselection start=\"2026-06-02\" end=\"2026-06-08\">\n Questa settimana\n </mds-input-date-range-preselection>\n <mds-input-date-range-preselection start=\"2026-06-01\" end=\"2026-06-30\">\n Questo mese\n </mds-input-date-range-preselection>\n</mds-input-date-range>\n```\n\n#### Controlling the Auto-Close Delay\n\nBy default the calendar closes 500 ms after a complete range is picked. Set `delay=\"0\"` to keep it open until the user dismisses it manually, or increase the value for a longer grace period.\n\n```html\n<!-- Keep the calendar open after selection -->\n<mds-input-date-range delay=\"0\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<!-- Longer grace period: 1 second -->\n<mds-input-date-range delay=\"1000\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Styling Customization\n\nStyle the component only through its documented `--mds-input-date-range-*` CSS custom properties. Set them on the host or a parent selector; use Magma color tokens via `rgb(var(--<token>))` so dark mode keeps working.\n\n```css\n.filtro-avanzato mds-input-date-range {\n --mds-input-date-range-background: rgb(var(--tone-neutral-02));\n --mds-input-date-range-icon-color: rgb(var(--variant-secondary-03));\n --mds-input-date-range-fields-gap: 0 var(--spacing-400);\n}\n```\n",
|
|
14523
14431
|
"3. Antipattern": "Common incorrect uses of `<mds-input-date-range>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Omit the Named Slots\n\nThe host renders two named slots (`start` and `end`) and wires them together internally. Without slotted `<mds-input-date>` children the component has no visible inputs and no data to commit.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input-date-range start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n</mds-input-date-range>\n\n<!-- ✅ CORRECT -->\n<mds-input-date-range start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Slot Raw `<input>` Elements\n\nThe `start` and `end` slots expect [`mds-input-date`](../../mds-input-date) children. The host calls `.setValue()` and `.focusInput()` on the assigned element; a native `<input>` does not expose those methods and will break internal orchestration.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input-date-range>\n <input type=\"date\" slot=\"start\" />\n <input type=\"date\" slot=\"end\" />\n</mds-input-date-range>\n\n<!-- ✅ CORRECT -->\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Use Non-ISO Date Strings\n\n`startDate`, `endDate`, `min`, and `max` all require `YYYY-MM-DD` ISO format. Passing a locale-formatted string (e.g. `\"01/06/2026\"`) is silently invalid for Luxon's `DateTime.fromISO()` and leaves the range empty or unguarded.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input-date-range start-date=\"01/06/2026\" end-date=\"30/06/2026\" min=\"01/01/2026\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<!-- ✅ CORRECT -->\n<mds-input-date-range start-date=\"2026-06-01\" end-date=\"2026-06-30\" min=\"2026-01-01\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Listen to Native `change` or `input` Events\n\nThe component emits `mdsInputDateRangeValueChange` as a documented custom event. Native `change` / `input` events originate from inside the shadow DOM and do not bubble out reliably.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input-date-range id=\"range\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n<script>\n document.querySelector('#range').addEventListener('change', handler);\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-input-date-range id=\"range\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n<script>\n document.querySelector('#range').addEventListener('mdsInputDateRangeValueChange', handler);\n</script>\n```\n\n#### Do Not Set `delay=\"false\"` to Disable Auto-Close\n\n`delay` is a numeric prop, not a boolean. Setting it to the string `\"false\"` is truthy and parsed as `NaN`, which produces unexpected behavior. Use `delay=\"0\"` to keep the calendar open after selection.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input-date-range delay=\"false\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<!-- ✅ CORRECT -->\n<mds-input-date-range delay=\"0\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Slot Preselection Elements Without the Component's Calendar\n\n[`mds-input-date-range-preselection`](../../mds-input-date-range-preselection) children must be direct slotted children of `<mds-input-date-range>`. Placing them outside the component, or inside a wrapper div, breaks the internal query that wires preset clicks to the range.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n<mds-input-date-range-preselection start=\"2026-06-01\" end=\"2026-06-30\">\n Questo mese\n</mds-input-date-range-preselection>\n\n<!-- ✅ CORRECT -->\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n <mds-input-date-range-preselection start=\"2026-06-01\" end=\"2026-06-30\">\n Questo mese\n </mds-input-date-range-preselection>\n</mds-input-date-range>\n```\n\n#### Do Not Omit `name` When Inside a Form\n\nWithout `name` the component is form-associated but submits no named field, so the date range is invisible to the server and to `FormData`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<form action=\"/filtra\" method=\"get\">\n <mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n </mds-input-date-range>\n</form>\n\n<!-- ✅ CORRECT -->\n<form action=\"/filtra\" method=\"get\">\n <mds-input-date-range name=\"periodo\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n </mds-input-date-range>\n</form>\n```\n"
|
|
14524
14432
|
},
|
|
14525
14433
|
"props": [
|
|
14434
|
+
{
|
|
14435
|
+
"name": "accessibleName",
|
|
14436
|
+
"type": "string | undefined",
|
|
14437
|
+
"complexType": {
|
|
14438
|
+
"original": "string",
|
|
14439
|
+
"resolved": "string | undefined",
|
|
14440
|
+
"references": {}
|
|
14441
|
+
},
|
|
14442
|
+
"mutable": false,
|
|
14443
|
+
"attr": "aria-label",
|
|
14444
|
+
"reflectToAttr": false,
|
|
14445
|
+
"docs": "The accessible name of the range: each of the two fields is named after it and after the\nend of the range it covers, the visible \"from\" and \"to\" labels living in this shadow root,\nwhere no IDREF of the slotted fields could reach them.",
|
|
14446
|
+
"docsTags": [],
|
|
14447
|
+
"values": [
|
|
14448
|
+
{
|
|
14449
|
+
"type": "string"
|
|
14450
|
+
},
|
|
14451
|
+
{
|
|
14452
|
+
"type": "undefined"
|
|
14453
|
+
}
|
|
14454
|
+
],
|
|
14455
|
+
"optional": true,
|
|
14456
|
+
"required": false,
|
|
14457
|
+
"getter": false,
|
|
14458
|
+
"setter": false
|
|
14459
|
+
},
|
|
14526
14460
|
{
|
|
14527
14461
|
"name": "delay",
|
|
14528
14462
|
"type": "number",
|
|
@@ -14618,6 +14552,35 @@
|
|
|
14618
14552
|
"getter": false,
|
|
14619
14553
|
"setter": false
|
|
14620
14554
|
},
|
|
14555
|
+
{
|
|
14556
|
+
"name": "hideToday",
|
|
14557
|
+
"type": "boolean",
|
|
14558
|
+
"complexType": {
|
|
14559
|
+
"original": "boolean",
|
|
14560
|
+
"resolved": "boolean",
|
|
14561
|
+
"references": {}
|
|
14562
|
+
},
|
|
14563
|
+
"mutable": false,
|
|
14564
|
+
"attr": "hide-today",
|
|
14565
|
+
"reflectToAttr": true,
|
|
14566
|
+
"docs": "Hides the highlight on today's date in the calendar.",
|
|
14567
|
+
"docsTags": [
|
|
14568
|
+
{
|
|
14569
|
+
"name": "default",
|
|
14570
|
+
"text": "false"
|
|
14571
|
+
}
|
|
14572
|
+
],
|
|
14573
|
+
"default": "false",
|
|
14574
|
+
"values": [
|
|
14575
|
+
{
|
|
14576
|
+
"type": "boolean"
|
|
14577
|
+
}
|
|
14578
|
+
],
|
|
14579
|
+
"optional": false,
|
|
14580
|
+
"required": false,
|
|
14581
|
+
"getter": false,
|
|
14582
|
+
"setter": false
|
|
14583
|
+
},
|
|
14621
14584
|
{
|
|
14622
14585
|
"name": "max",
|
|
14623
14586
|
"type": "null | string",
|
|
@@ -14798,28 +14761,6 @@
|
|
|
14798
14761
|
"text": "event the preselection range to apply"
|
|
14799
14762
|
}
|
|
14800
14763
|
]
|
|
14801
|
-
},
|
|
14802
|
-
{
|
|
14803
|
-
"name": "updateLang",
|
|
14804
|
-
"returns": {
|
|
14805
|
-
"type": "Promise<void>",
|
|
14806
|
-
"docs": ""
|
|
14807
|
-
},
|
|
14808
|
-
"complexType": {
|
|
14809
|
-
"signature": "() => Promise<void>",
|
|
14810
|
-
"parameters": [],
|
|
14811
|
-
"references": {
|
|
14812
|
-
"Promise": {
|
|
14813
|
-
"location": "global",
|
|
14814
|
-
"id": "global::Promise"
|
|
14815
|
-
}
|
|
14816
|
-
},
|
|
14817
|
-
"return": "Promise<void>"
|
|
14818
|
-
},
|
|
14819
|
-
"signature": "updateLang() => Promise<void>",
|
|
14820
|
-
"parameters": [],
|
|
14821
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
14822
|
-
"docsTags": []
|
|
14823
14764
|
}
|
|
14824
14765
|
],
|
|
14825
14766
|
"events": [
|
|
@@ -15274,6 +15215,32 @@
|
|
|
15274
15215
|
"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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Set `autosubmit=\"false\"` to Disable Auto-Submit\n\nAny non-empty string attribute is truthy in HTML and Stencil. Setting `autosubmit=\"false\"` does not turn the feature off - it turns it on. 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: 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"
|
|
15275
15216
|
},
|
|
15276
15217
|
"props": [
|
|
15218
|
+
{
|
|
15219
|
+
"name": "accessibleName",
|
|
15220
|
+
"type": "string | undefined",
|
|
15221
|
+
"complexType": {
|
|
15222
|
+
"original": "string",
|
|
15223
|
+
"resolved": "string | undefined",
|
|
15224
|
+
"references": {}
|
|
15225
|
+
},
|
|
15226
|
+
"mutable": false,
|
|
15227
|
+
"attr": "aria-label",
|
|
15228
|
+
"reflectToAttr": false,
|
|
15229
|
+
"docs": "The accessible name of the code: each digit is announced as a position inside it, the\nfields being separate controls a screen reader reaches one at a time.",
|
|
15230
|
+
"docsTags": [],
|
|
15231
|
+
"values": [
|
|
15232
|
+
{
|
|
15233
|
+
"type": "string"
|
|
15234
|
+
},
|
|
15235
|
+
{
|
|
15236
|
+
"type": "undefined"
|
|
15237
|
+
}
|
|
15238
|
+
],
|
|
15239
|
+
"optional": true,
|
|
15240
|
+
"required": false,
|
|
15241
|
+
"getter": false,
|
|
15242
|
+
"setter": false
|
|
15243
|
+
},
|
|
15277
15244
|
{
|
|
15278
15245
|
"name": "autosubmit",
|
|
15279
15246
|
"type": "boolean",
|
|
@@ -15729,6 +15696,32 @@
|
|
|
15729
15696
|
"3. Antipattern": "Common incorrect uses of `<mds-input-select>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Slot Non-Option Elements\n\nThe default slot is reserved for `<option>` and `<optgroup>` elements. The component clones slot children into the inner `<select>`; any other element is copied verbatim and makes the native select malformed.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input-select name=\"categoria\">\n <div class=\"option-group\">\n <span>Notizie</span>\n <span>Eventi</span>\n </div>\n</mds-input-select>\n\n<!-- ✅ CORRECT -->\n<mds-input-select name=\"categoria\" placeholder=\"Seleziona...\">\n <option value=\"news\">Notizie</option>\n <option value=\"eventi\">Eventi</option>\n</mds-input-select>\n```\n\n#### Do Not Listen to the Native `change` Event\n\n`<mds-input-select>` wraps a shadow-DOM `<select>`; the native `change` event does not bubble out of shadow DOM reliably. Always listen to the documented `mdsInputSelectChange` custom event instead.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input-select id=\"sel\" name=\"tipo\"></mds-input-select>\n<script>\n document.getElementById('sel').addEventListener('change', (e) => {\n console.log(e.target.value); // may be undefined or stale\n });\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-input-select id=\"sel\" name=\"tipo\"></mds-input-select>\n<script>\n document.getElementById('sel').addEventListener('mdsInputSelectChange', (e) => {\n console.log(e.detail.value);\n });\n</script>\n```\n\n#### Do Not Set `size` Without `multiple`\n\n`size` controls how many rows are visible in the list box. Outside of `multiple` mode the native `<select>` ignores this attribute, so it has no visual effect and signals a misunderstanding of the API.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-input-select name=\"stato\" size=\"5\">\n <option value=\"A\">Aperta</option>\n <option value=\"C\">Chiusa</option>\n</mds-input-select>\n\n<!-- ✅ CORRECT - size is meaningful only with multiple -->\n<mds-input-select name=\"stati\" multiple size=\"5\">\n <option value=\"A\">Aperta</option>\n <option value=\"C\">Chiusa</option>\n <option value=\"S\">Sospesa</option>\n</mds-input-select>\n```\n\n#### Do Not Use `variant` for Decorative Styling\n\n`variant` maps to `ThemeStatusVariantType` (`error`, `success`, `warning`, `info`). It is meant to communicate a validation outcome, not to apply a brand color. Using a status variant to make the component visually match a section's color theme misleads users about the control's validation state.\n\n```html\n<!-- 🚫 INCORRECT - using 'info' just for a blue accent -->\n<mds-input-select name=\"argomento\" variant=\"info\">\n <option value=\"A\">Argomento A</option>\n</mds-input-select>\n\n<!-- ✅ CORRECT - set variant only to reflect real validation state -->\n<mds-input-select name=\"argomento\" variant=\"error\" required placeholder=\"Obbligatorio\">\n <option value=\"A\">Argomento A</option>\n</mds-input-select>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Inner `<select>`\n\nThe supported customization surface is the documented `--mds-input-select-*` CSS custom properties and the two shadow parts (`select`, `tip-top`). Targeting internal elements with `>>>` or undocumented selectors couples your code to the implementation and breaks on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-input-select >>> select {\n font-size: 1rem;\n border: 2px solid red;\n}\n\n/* ✅ CORRECT */\nmds-input-select {\n --mds-input-select-ring: 0 0 0 2px rgb(var(--status-error-05));\n --mds-input-select-variant-color-rgb: var(--status-error-05);\n}\nmds-input-select::part(select) {\n font-size: 1rem;\n}\n```\n\n#### Do Not Set `placeholder` When You Need a Real Default Selection\n\n`placeholder` injects an empty-value leading option that disappears from valid choices once `required` is set. If you want the component to open with a specific option pre-selected, use `value` or `default-value` instead.\n\n```html\n<!-- 🚫 INCORRECT - a real value supplied as placeholder text -->\n<mds-input-select name=\"priorita\" placeholder=\"Media\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n\n<!-- ✅ CORRECT - use value to pre-select a real option -->\n<mds-input-select name=\"priorita\" value=\"media\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n```\n\n#### Do Not Replace with a Raw `<select>`\n\n`<mds-input-select>` provides theming, accessible status tips, form-reset integration, and dark/high-contrast support. Reaching for a plain `<select>` bypasses all of that and breaks visual consistency across themes.\n\n```html\n<!-- 🚫 INCORRECT -->\n<select name=\"categoria\" class=\"form-select\">\n <option value=\"\">Seleziona...</option>\n <option value=\"A\">Categoria A</option>\n</select>\n\n<!-- ✅ CORRECT -->\n<mds-input-select name=\"categoria\" placeholder=\"Seleziona...\">\n <option value=\"A\">Categoria A</option>\n</mds-input-select>\n```\n"
|
|
15730
15697
|
},
|
|
15731
15698
|
"props": [
|
|
15699
|
+
{
|
|
15700
|
+
"name": "accessibleName",
|
|
15701
|
+
"type": "string | undefined",
|
|
15702
|
+
"complexType": {
|
|
15703
|
+
"original": "string",
|
|
15704
|
+
"resolved": "string | undefined",
|
|
15705
|
+
"references": {}
|
|
15706
|
+
},
|
|
15707
|
+
"mutable": false,
|
|
15708
|
+
"attr": "aria-label",
|
|
15709
|
+
"reflectToAttr": false,
|
|
15710
|
+
"docs": "The accessible name of the native control: the label a screen reader announces. An\n`mds-input-field` around the component passes its own label down here, so the attribute\nis only written by hand when the control stands on its own. The placeholder is deliberately\nnot a fallback: it disappears as soon as the field is filled.",
|
|
15711
|
+
"docsTags": [],
|
|
15712
|
+
"values": [
|
|
15713
|
+
{
|
|
15714
|
+
"type": "string"
|
|
15715
|
+
},
|
|
15716
|
+
{
|
|
15717
|
+
"type": "undefined"
|
|
15718
|
+
}
|
|
15719
|
+
],
|
|
15720
|
+
"optional": true,
|
|
15721
|
+
"required": false,
|
|
15722
|
+
"getter": false,
|
|
15723
|
+
"setter": false
|
|
15724
|
+
},
|
|
15732
15725
|
{
|
|
15733
15726
|
"name": "autoFocus",
|
|
15734
15727
|
"type": "boolean | undefined",
|
|
@@ -16113,28 +16106,6 @@
|
|
|
16113
16106
|
],
|
|
16114
16107
|
"docs": "Sets the value of the component",
|
|
16115
16108
|
"docsTags": []
|
|
16116
|
-
},
|
|
16117
|
-
{
|
|
16118
|
-
"name": "updateLang",
|
|
16119
|
-
"returns": {
|
|
16120
|
-
"type": "Promise<void>",
|
|
16121
|
-
"docs": ""
|
|
16122
|
-
},
|
|
16123
|
-
"complexType": {
|
|
16124
|
-
"signature": "() => Promise<void>",
|
|
16125
|
-
"parameters": [],
|
|
16126
|
-
"references": {
|
|
16127
|
-
"Promise": {
|
|
16128
|
-
"location": "global",
|
|
16129
|
-
"id": "global::Promise"
|
|
16130
|
-
}
|
|
16131
|
-
},
|
|
16132
|
-
"return": "Promise<void>"
|
|
16133
|
-
},
|
|
16134
|
-
"signature": "updateLang() => Promise<void>",
|
|
16135
|
-
"parameters": [],
|
|
16136
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
16137
|
-
"docsTags": []
|
|
16138
16109
|
}
|
|
16139
16110
|
],
|
|
16140
16111
|
"events": [
|
|
@@ -16227,11 +16198,13 @@
|
|
|
16227
16198
|
"states": [],
|
|
16228
16199
|
"dependents": [],
|
|
16229
16200
|
"dependencies": [
|
|
16201
|
+
"mds-icon",
|
|
16230
16202
|
"mds-input-tip",
|
|
16231
16203
|
"mds-input-tip-item"
|
|
16232
16204
|
],
|
|
16233
16205
|
"dependencyGraph": {
|
|
16234
16206
|
"mds-input-select": [
|
|
16207
|
+
"mds-icon",
|
|
16235
16208
|
"mds-input-tip",
|
|
16236
16209
|
"mds-input-tip-item"
|
|
16237
16210
|
],
|
|
@@ -16678,30 +16651,7 @@
|
|
|
16678
16651
|
"setter": false
|
|
16679
16652
|
}
|
|
16680
16653
|
],
|
|
16681
|
-
"methods": [
|
|
16682
|
-
{
|
|
16683
|
-
"name": "updateLang",
|
|
16684
|
-
"returns": {
|
|
16685
|
-
"type": "Promise<void>",
|
|
16686
|
-
"docs": ""
|
|
16687
|
-
},
|
|
16688
|
-
"complexType": {
|
|
16689
|
-
"signature": "() => Promise<void>",
|
|
16690
|
-
"parameters": [],
|
|
16691
|
-
"references": {
|
|
16692
|
-
"Promise": {
|
|
16693
|
-
"location": "global",
|
|
16694
|
-
"id": "global::Promise"
|
|
16695
|
-
}
|
|
16696
|
-
},
|
|
16697
|
-
"return": "Promise<void>"
|
|
16698
|
-
},
|
|
16699
|
-
"signature": "updateLang() => Promise<void>",
|
|
16700
|
-
"parameters": [],
|
|
16701
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
16702
|
-
"docsTags": []
|
|
16703
|
-
}
|
|
16704
|
-
],
|
|
16654
|
+
"methods": [],
|
|
16705
16655
|
"events": [
|
|
16706
16656
|
{
|
|
16707
16657
|
"event": "mdsInputSwitchChange",
|
|
@@ -17164,30 +17114,7 @@
|
|
|
17164
17114
|
"setter": false
|
|
17165
17115
|
}
|
|
17166
17116
|
],
|
|
17167
|
-
"methods": [
|
|
17168
|
-
{
|
|
17169
|
-
"name": "updateLang",
|
|
17170
|
-
"returns": {
|
|
17171
|
-
"type": "Promise<void>",
|
|
17172
|
-
"docs": ""
|
|
17173
|
-
},
|
|
17174
|
-
"complexType": {
|
|
17175
|
-
"signature": "() => Promise<void>",
|
|
17176
|
-
"parameters": [],
|
|
17177
|
-
"references": {
|
|
17178
|
-
"Promise": {
|
|
17179
|
-
"location": "global",
|
|
17180
|
-
"id": "global::Promise"
|
|
17181
|
-
}
|
|
17182
|
-
},
|
|
17183
|
-
"return": "Promise<void>"
|
|
17184
|
-
},
|
|
17185
|
-
"signature": "updateLang() => Promise<void>",
|
|
17186
|
-
"parameters": [],
|
|
17187
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
17188
|
-
"docsTags": []
|
|
17189
|
-
}
|
|
17190
|
-
],
|
|
17117
|
+
"methods": [],
|
|
17191
17118
|
"events": [],
|
|
17192
17119
|
"listeners": [],
|
|
17193
17120
|
"styles": [
|
|
@@ -17490,28 +17417,6 @@
|
|
|
17490
17417
|
"parameters": [],
|
|
17491
17418
|
"docs": "Reset component's files",
|
|
17492
17419
|
"docsTags": []
|
|
17493
|
-
},
|
|
17494
|
-
{
|
|
17495
|
-
"name": "updateLang",
|
|
17496
|
-
"returns": {
|
|
17497
|
-
"type": "Promise<void>",
|
|
17498
|
-
"docs": ""
|
|
17499
|
-
},
|
|
17500
|
-
"complexType": {
|
|
17501
|
-
"signature": "() => Promise<void>",
|
|
17502
|
-
"parameters": [],
|
|
17503
|
-
"references": {
|
|
17504
|
-
"Promise": {
|
|
17505
|
-
"location": "global",
|
|
17506
|
-
"id": "global::Promise"
|
|
17507
|
-
}
|
|
17508
|
-
},
|
|
17509
|
-
"return": "Promise<void>"
|
|
17510
|
-
},
|
|
17511
|
-
"signature": "updateLang() => Promise<void>",
|
|
17512
|
-
"parameters": [],
|
|
17513
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
17514
|
-
"docsTags": []
|
|
17515
17420
|
}
|
|
17516
17421
|
],
|
|
17517
17422
|
"events": [
|
|
@@ -17701,30 +17606,7 @@
|
|
|
17701
17606
|
"setter": false
|
|
17702
17607
|
}
|
|
17703
17608
|
],
|
|
17704
|
-
"methods": [
|
|
17705
|
-
{
|
|
17706
|
-
"name": "updateLang",
|
|
17707
|
-
"returns": {
|
|
17708
|
-
"type": "Promise<void>",
|
|
17709
|
-
"docs": ""
|
|
17710
|
-
},
|
|
17711
|
-
"complexType": {
|
|
17712
|
-
"signature": "() => Promise<void>",
|
|
17713
|
-
"parameters": [],
|
|
17714
|
-
"references": {
|
|
17715
|
-
"Promise": {
|
|
17716
|
-
"location": "global",
|
|
17717
|
-
"id": "global::Promise"
|
|
17718
|
-
}
|
|
17719
|
-
},
|
|
17720
|
-
"return": "Promise<void>"
|
|
17721
|
-
},
|
|
17722
|
-
"signature": "updateLang() => Promise<void>",
|
|
17723
|
-
"parameters": [],
|
|
17724
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
17725
|
-
"docsTags": []
|
|
17726
|
-
}
|
|
17727
|
-
],
|
|
17609
|
+
"methods": [],
|
|
17728
17610
|
"events": [],
|
|
17729
17611
|
"listeners": [],
|
|
17730
17612
|
"styles": [
|
|
@@ -18250,33 +18132,10 @@
|
|
|
18250
18132
|
"setter": false
|
|
18251
18133
|
}
|
|
18252
18134
|
],
|
|
18253
|
-
"methods": [
|
|
18254
|
-
|
|
18255
|
-
|
|
18256
|
-
|
|
18257
|
-
"type": "Promise<void>",
|
|
18258
|
-
"docs": ""
|
|
18259
|
-
},
|
|
18260
|
-
"complexType": {
|
|
18261
|
-
"signature": "() => Promise<void>",
|
|
18262
|
-
"parameters": [],
|
|
18263
|
-
"references": {
|
|
18264
|
-
"Promise": {
|
|
18265
|
-
"location": "global",
|
|
18266
|
-
"id": "global::Promise"
|
|
18267
|
-
}
|
|
18268
|
-
},
|
|
18269
|
-
"return": "Promise<void>"
|
|
18270
|
-
},
|
|
18271
|
-
"signature": "updateLang() => Promise<void>",
|
|
18272
|
-
"parameters": [],
|
|
18273
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
18274
|
-
"docsTags": []
|
|
18275
|
-
}
|
|
18276
|
-
],
|
|
18277
|
-
"events": [],
|
|
18278
|
-
"listeners": [],
|
|
18279
|
-
"styles": [
|
|
18135
|
+
"methods": [],
|
|
18136
|
+
"events": [],
|
|
18137
|
+
"listeners": [],
|
|
18138
|
+
"styles": [
|
|
18280
18139
|
{
|
|
18281
18140
|
"name": "--mds-keyboard-key-illumination-dark",
|
|
18282
18141
|
"annotation": "prop",
|
|
@@ -18567,8 +18426,8 @@
|
|
|
18567
18426
|
"docsTags": [],
|
|
18568
18427
|
"usage": {
|
|
18569
18428
|
"1. Description": "The `<mds-label>` web component is the Magma Design System tag/chip used to display a short, non-interactive piece of text such as a status, a category, or a removable selection.\n\n#### Semantic Behavior\n\n- **Text content**: The visible text comes from the `label` prop; the default slot is documented for text only - avoid placing HTML elements or components in it.\n- **Deletable affordance**: When `deletable` is set, the component renders a trailing close button and emits the `mdsLabelDelete` event on activation; the deletion does not bubble to a surrounding clickable container.\n- **Keyboard interaction**: While `deletable`, the close button can be triggered by keyboard as well as pointer.\n- **Localization**: The close button's `title` is localized (el/en/es/it).\n\n#### Properties & Visual Configurations\n\nThe `variant` and `tone` props follow the shared ladders defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); `tone` is limited to the minimal `'strong'` / `'weak'` set and defaults to `'weak'`.\n\n#### Component-specific variants and tones\n\n`variant` accepts both the theme label palette (e.g. `'sky'`, the default) and the status palette (`'error'`, `'warning'`, `'success'`, `'info'`). Pick a status value when the label communicates an outcome or state; pick a theme color when it is a neutral category or decorative tag.\n\n#### Other behavioral props\n\n- **`truncate`** controls overflow handling of the inner text: `'word'` (default) keeps it on one line, `'all'` truncates aggressively, and `'none'` allows multiline wrapping.\n- **`typography`** selects a compact type scale (`'caption'`, `'detail'`, `'tip'`) appropriate to the label's small footprint, defaulting to `'caption'`.\n",
|
|
18570
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-label>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Label via `label` Prop\n\nThe canonical form. Use the `label` prop for the text; it is the only way to set visible content because the component renders no `<slot>` element.\n\n```html\n<mds-label label=\"Categoria\"></mds-label>\n```\n\n#### Decorative Color via `variant`\n\nPick from the twelve label palette colors for neutral, decorative tags. Default is `sky`; change only when the color carries meaning to the user.\n\n```html\n<mds-label label=\"Ambiente\" variant=\"green\"></mds-label>\n<mds-label label=\"Priorita'\" variant=\"orange\"></mds-label>\n<mds-label label=\"Archivio\" variant=\"violet\"></mds-label>\n<mds-label label=\"Bozza\" variant=\"sky\"></mds-label>\n```\n\n#### Status Variant for Outcome Communication\n\nUse a status variant when the label communicates a system outcome or validation state, not just a decorative category.\n\n```html\n<mds-label label=\"Approvato\" variant=\"success\"></mds-label>\n<mds-label label=\"In attesa\" variant=\"warning\"></mds-label>\n<mds-label label=\"Rifiutato\" variant=\"error\"></mds-label>\n<mds-label label=\"Informazione\" variant=\"info\"></mds-label>\n```\n\n#### Tone for Emphasis\n\nPair `tone=\"strong\"` for higher-contrast situations; the default `weak` is lighter and suits most inline contexts.\n\n```html\n<!-- Default: subtle tinted background -->\n<mds-label label=\"Etichetta\" variant=\"blue\" tone=\"weak\"></mds-label>\n\n<!-- Higher contrast: solid background -->\n<mds-label label=\"Etichetta\" variant=\"blue\" tone=\"strong\"></mds-label>\n```\n\n#### Deletable Label with `mdsLabelDelete` Event\n\nSet `deletable` to render the trailing close button. Listen to `mdsLabelDelete` to remove the label from your model; the close button stops event propagation so clicks do not reach a surrounding interactive container.\n\n```html\n<mds-label label=\"Tag rimovibile\" variant=\"purple\" deletable></mds-label>\n```\n\n```javascript\ndocument.querySelector('mds-label').addEventListener('mdsLabelDelete', () => {\n // rimuovi il tag dal modello\n});\n```\n\n#### Truncation Control via `truncate`\n\nUse `truncate=\"word\"` (default) to clamp to one line on word boundaries. Use `truncate=\"none\"` to allow multiline wrapping inside a constrained container.\n\n```html\n<!-- Single-line truncation (default) -->\n<mds-label\n label=\"Testo molto lungo che supera il limite\"\n truncate=\"word\"\n variant=\"lime\"\n class=\"w-3200\"\n></mds-label>\n\n<!-- Multiline inside a narrow container -->\n<mds-label\n label=\"Testo molto lungo che supera il limite\"\n truncate=\"none\"\n variant=\"lime\"\n class=\"w-3200\"\n></mds-label>\n```\n\n#### Typography Scale\n\nChoose `typography` to match the surrounding text hierarchy. The default `caption` suits most label contexts; use `detail` or `tip` only when the label sits alongside even smaller text.\n\n```html\n<mds-label label=\"Caption (default)\" variant=\"aqua\" typography=\"caption\"></mds-label>\n<mds-label label=\"Detail\" variant=\"aqua\" typography=\"detail\"></mds-label>\n<mds-label label=\"Tip\" variant=\"aqua\" typography=\"tip\"></mds-label>\n```\n\n#### Styling Customization\n\nStyle the label only through its documented `--mds-label-*` CSS custom properties. Set them on the host or a parent selector; use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.categoria-speciale mds-label {\n --mds-label-background: rgb(var(--label-orchid-08));\n --mds-label-color: rgb(var(--label-orchid-02));\n --mds-label-
|
|
18571
|
-
"3. Antipattern": "Common incorrect uses of `<mds-label>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Rely on the Default Slot for Visible Text\n\nThe component's `render()` method does not include a `<slot>` element, so content placed in the default slot is never rendered. Use the `label` prop exclusively.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-label>Stato documento</mds-label>\n\n<!-- ✅ CORRECT -->\n<mds-label label=\"Stato documento\"></mds-label>\n```\n\n#### Do Not Use `<mds-label>` as a Form Input Label\n\n`<mds-label>` is a standalone decorative tag for categories and statuses. It is not a replacement for `<label>` or for `mds-input-field`'s label slot, and it has no `for` / `htmlFor` association with form controls.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-label label=\"Nome utente\"></mds-label>\n<mds-input name=\"username\"></mds-input>\n\n<!-- ✅ CORRECT -->\n<mds-input-field>\n <span slot=\"label\">Nome utente</span>\n <mds-input slot=\"input\" name=\"username\"></mds-input>\n</mds-input-field>\n```\n\n#### Do Not Set `deletable=\"false\"` as a String\n\n`deletable` is a boolean prop. Setting it to the string `\"false\"` is truthy in HTML and enables the close button. Remove the attribute entirely to disable the affordance.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-label label=\"Tag\" deletable=\"false\"></mds-label>\n\n<!-- ✅ CORRECT -->\n<mds-label label=\"Tag\"></mds-label>\n```\n\n#### Do Not Use a Status Variant for Decorative Tags\n\nStatus variants (`error`, `warning`, `success`, `info`) communicate system outcomes. Using them for neutral categories misleads users about the meaning of the label.\n\n```html\n<!-- 🚫 INCORRECT: \"Fauna\" is a category, not an error state -->\n<mds-label label=\"Fauna\" variant=\"error\"></mds-label>\n\n<!-- ✅ CORRECT: use a decorative palette color -->\n<mds-label label=\"Fauna\" variant=\"green\"></mds-label>\n```\n\n#### Do Not Nest Interactive Elements Inside `<mds-label>`\n\nThe component renders no slot; placing buttons or links in the default slot position has no effect. For a deletable label use `deletable` and listen to `mdsLabelDelete`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-label label=\"Categoria\">\n <button onclick=\"remove()\">x</button>\n</mds-label>\n\n<!-- ✅ CORRECT -->\n<mds-label label=\"Categoria\" deletable></mds-label>\n```\n\n#### Customize via Documented Vars, Not Internal Selectors\n\nThe supported customization surface is `--mds-label-*` CSS custom properties. Targeting shadow internals via `::part()`, `>>>`, or undocumented class names couples your code to the Shadow DOM implementation and will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-label >>> .text {\n font-weight: bold;\n}\n\n/* ✅ CORRECT */\nmds-label {\n --mds-label-background: rgb(var(--label-blue-08));\n --mds-label-color: rgb(var(--label-blue-02));\n
|
|
18429
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-label>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Label via `label` Prop\n\nThe canonical form. Use the `label` prop for the text; it is the only way to set visible content because the component renders no `<slot>` element.\n\n```html\n<mds-label label=\"Categoria\"></mds-label>\n```\n\n#### Decorative Color via `variant`\n\nPick from the twelve label palette colors for neutral, decorative tags. Default is `sky`; change only when the color carries meaning to the user.\n\n```html\n<mds-label label=\"Ambiente\" variant=\"green\"></mds-label>\n<mds-label label=\"Priorita'\" variant=\"orange\"></mds-label>\n<mds-label label=\"Archivio\" variant=\"violet\"></mds-label>\n<mds-label label=\"Bozza\" variant=\"sky\"></mds-label>\n```\n\n#### Status Variant for Outcome Communication\n\nUse a status variant when the label communicates a system outcome or validation state, not just a decorative category.\n\n```html\n<mds-label label=\"Approvato\" variant=\"success\"></mds-label>\n<mds-label label=\"In attesa\" variant=\"warning\"></mds-label>\n<mds-label label=\"Rifiutato\" variant=\"error\"></mds-label>\n<mds-label label=\"Informazione\" variant=\"info\"></mds-label>\n```\n\n#### Tone for Emphasis\n\nPair `tone=\"strong\"` for higher-contrast situations; the default `weak` is lighter and suits most inline contexts.\n\n```html\n<!-- Default: subtle tinted background -->\n<mds-label label=\"Etichetta\" variant=\"blue\" tone=\"weak\"></mds-label>\n\n<!-- Higher contrast: solid background -->\n<mds-label label=\"Etichetta\" variant=\"blue\" tone=\"strong\"></mds-label>\n```\n\n#### Deletable Label with `mdsLabelDelete` Event\n\nSet `deletable` to render the trailing close button. Listen to `mdsLabelDelete` to remove the label from your model; the close button stops event propagation so clicks do not reach a surrounding interactive container.\n\n```html\n<mds-label label=\"Tag rimovibile\" variant=\"purple\" deletable></mds-label>\n```\n\n```javascript\ndocument.querySelector('mds-label').addEventListener('mdsLabelDelete', () => {\n // rimuovi il tag dal modello\n});\n```\n\n#### Truncation Control via `truncate`\n\nUse `truncate=\"word\"` (default) to clamp to one line on word boundaries. Use `truncate=\"none\"` to allow multiline wrapping inside a constrained container.\n\n```html\n<!-- Single-line truncation (default) -->\n<mds-label\n label=\"Testo molto lungo che supera il limite\"\n truncate=\"word\"\n variant=\"lime\"\n class=\"w-3200\"\n></mds-label>\n\n<!-- Multiline inside a narrow container -->\n<mds-label\n label=\"Testo molto lungo che supera il limite\"\n truncate=\"none\"\n variant=\"lime\"\n class=\"w-3200\"\n></mds-label>\n```\n\n#### Typography Scale\n\nChoose `typography` to match the surrounding text hierarchy. The default `caption` suits most label contexts; use `detail` or `tip` only when the label sits alongside even smaller text.\n\n```html\n<mds-label label=\"Caption (default)\" variant=\"aqua\" typography=\"caption\"></mds-label>\n<mds-label label=\"Detail\" variant=\"aqua\" typography=\"detail\"></mds-label>\n<mds-label label=\"Tip\" variant=\"aqua\" typography=\"tip\"></mds-label>\n```\n\n#### Styling Customization\n\nStyle the label only through its documented `--mds-label-*` CSS custom properties. Set them on the host or a parent selector; use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.categoria-speciale mds-label {\n --mds-label-background: rgb(var(--label-orchid-08));\n --mds-label-color: rgb(var(--label-orchid-02));\n --mds-label-button-background: rgb(var(--label-orchid-07));\n --mds-label-button-icon-color: rgb(var(--label-orchid-03));\n}\n```\n",
|
|
18430
|
+
"3. Antipattern": "Common incorrect uses of `<mds-label>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Rely on the Default Slot for Visible Text\n\nThe component's `render()` method does not include a `<slot>` element, so content placed in the default slot is never rendered. Use the `label` prop exclusively.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-label>Stato documento</mds-label>\n\n<!-- ✅ CORRECT -->\n<mds-label label=\"Stato documento\"></mds-label>\n```\n\n#### Do Not Use `<mds-label>` as a Form Input Label\n\n`<mds-label>` is a standalone decorative tag for categories and statuses. It is not a replacement for `<label>` or for `mds-input-field`'s label slot, and it has no `for` / `htmlFor` association with form controls.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-label label=\"Nome utente\"></mds-label>\n<mds-input name=\"username\"></mds-input>\n\n<!-- ✅ CORRECT -->\n<mds-input-field>\n <span slot=\"label\">Nome utente</span>\n <mds-input slot=\"input\" name=\"username\"></mds-input>\n</mds-input-field>\n```\n\n#### Do Not Set `deletable=\"false\"` as a String\n\n`deletable` is a boolean prop. Setting it to the string `\"false\"` is truthy in HTML and enables the close button. Remove the attribute entirely to disable the affordance.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-label label=\"Tag\" deletable=\"false\"></mds-label>\n\n<!-- ✅ CORRECT -->\n<mds-label label=\"Tag\"></mds-label>\n```\n\n#### Do Not Use a Status Variant for Decorative Tags\n\nStatus variants (`error`, `warning`, `success`, `info`) communicate system outcomes. Using them for neutral categories misleads users about the meaning of the label.\n\n```html\n<!-- 🚫 INCORRECT: \"Fauna\" is a category, not an error state -->\n<mds-label label=\"Fauna\" variant=\"error\"></mds-label>\n\n<!-- ✅ CORRECT: use a decorative palette color -->\n<mds-label label=\"Fauna\" variant=\"green\"></mds-label>\n```\n\n#### Do Not Nest Interactive Elements Inside `<mds-label>`\n\nThe component renders no slot; placing buttons or links in the default slot position has no effect. For a deletable label use `deletable` and listen to `mdsLabelDelete`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-label label=\"Categoria\">\n <button onclick=\"remove()\">x</button>\n</mds-label>\n\n<!-- ✅ CORRECT -->\n<mds-label label=\"Categoria\" deletable></mds-label>\n```\n\n#### Customize via Documented Vars, Not Internal Selectors\n\nThe supported customization surface is `--mds-label-*` CSS custom properties. Targeting shadow internals via `::part()`, `>>>`, or undocumented class names couples your code to the Shadow DOM implementation and will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-label >>> .text {\n font-weight: bold;\n}\n\n/* ✅ CORRECT */\nmds-label {\n --mds-label-background: rgb(var(--label-blue-08));\n --mds-label-color: rgb(var(--label-blue-02));\n}\n```\n"
|
|
18572
18431
|
},
|
|
18573
18432
|
"props": [
|
|
18574
18433
|
{
|
|
@@ -18857,30 +18716,7 @@
|
|
|
18857
18716
|
"setter": false
|
|
18858
18717
|
}
|
|
18859
18718
|
],
|
|
18860
|
-
"methods": [
|
|
18861
|
-
{
|
|
18862
|
-
"name": "updateLang",
|
|
18863
|
-
"returns": {
|
|
18864
|
-
"type": "Promise<void>",
|
|
18865
|
-
"docs": ""
|
|
18866
|
-
},
|
|
18867
|
-
"complexType": {
|
|
18868
|
-
"signature": "() => Promise<void>",
|
|
18869
|
-
"parameters": [],
|
|
18870
|
-
"references": {
|
|
18871
|
-
"Promise": {
|
|
18872
|
-
"location": "global",
|
|
18873
|
-
"id": "global::Promise"
|
|
18874
|
-
}
|
|
18875
|
-
},
|
|
18876
|
-
"return": "Promise<void>"
|
|
18877
|
-
},
|
|
18878
|
-
"signature": "updateLang() => Promise<void>",
|
|
18879
|
-
"parameters": [],
|
|
18880
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
18881
|
-
"docsTags": []
|
|
18882
|
-
}
|
|
18883
|
-
],
|
|
18719
|
+
"methods": [],
|
|
18884
18720
|
"events": [
|
|
18885
18721
|
{
|
|
18886
18722
|
"event": "mdsLabelDelete",
|
|
@@ -18929,11 +18765,6 @@
|
|
|
18929
18765
|
"annotation": "prop",
|
|
18930
18766
|
"docs": "The color applied to any icon inside the label."
|
|
18931
18767
|
},
|
|
18932
|
-
{
|
|
18933
|
-
"name": "--mds-label-radius",
|
|
18934
|
-
"annotation": "prop",
|
|
18935
|
-
"docs": "The border-radius of the label."
|
|
18936
|
-
},
|
|
18937
18768
|
{
|
|
18938
18769
|
"name": "--mds-label-selection-background",
|
|
18939
18770
|
"annotation": "prop",
|
|
@@ -19198,11 +19029,37 @@
|
|
|
19198
19029
|
"docs": "",
|
|
19199
19030
|
"docsTags": [],
|
|
19200
19031
|
"usage": {
|
|
19201
|
-
"1. Description": "The `<mds-mention>` web component renders a compact inline chip that references a person or entity - the kind of token produced when you type `@name` in an editor or comment field. It pairs an icon, a text label, and a removable action into a single self-contained pill.\n\n#### Semantic Behavior\n\n- **Props-only**: It has no default slot and exposes its content exclusively through props.\n- **Default icon**: When `icon` is not set the component falls back to the `alternate-email` (`@`) glyph, reinforcing the mention metaphor.\n- **
|
|
19202
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-mention>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Inline Mention\n\nThe canonical form. Provide `label` with the user handle or display name. The component renders the default `@` glyph
|
|
19203
|
-
"3. Antipattern": "Common incorrect uses of `<mds-mention>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Slot Content Into the Component\n\n`<mds-mention>` has no default slot and no named slots. Any child nodes placed inside the tag are silently ignored. Pass all content through the `label` and `icon` props.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-mention>\n <mds-icon name=\"mi/baseline/person\"></mds-icon>\n mario.rossi\n</mds-mention>\n\n<!-- ✅ CORRECT -->\n<mds-mention label=\"mario.rossi\" icon=\"mi/baseline/person\"></mds-mention>\n```\n\n#### Do Not Use a Raw `<span>` Chip Instead of the Component\n\nWrapping text in a styled `<span>` misses the
|
|
19032
|
+
"1. Description": "The `<mds-mention>` web component renders a compact inline chip that references a person or entity - the kind of token produced when you type `@name` in an editor or comment field. It pairs an icon, a text label, and a removable action into a single self-contained pill.\n\n#### Semantic Behavior\n\n- **Props-only**: It has no default slot and exposes its content exclusively through props.\n- **Default icon**: When `icon` is not set the component falls back to the `alternate-email` (`@`) glyph, reinforcing the mention metaphor.\n- **Opt-in remove affordance**: `deletable` adds a trailing remove button; its click emits `mdsMentionDelete`, and the component leaves the removal itself to the application.\n- **Size-driven typography**: `size` maps to a fixed typography ramp (`sm` → `caption`, `md` → `detail`, `lg` → `h6`); the label is bold at `sm` and `md`, and normal weight at `lg`.\n\n#### Properties & Visual Configurations\n\n- **`deletable`** turns on the trailing remove button. Without it the mention is a read-only token: no button, no event.\n- **`icon`** is an SVG filename slug from the Magma icon library, shown at the left of the label; omit it to keep the default `@` mention glyph.\n- **`size`** controls both the physical scale and the typography of the label - pick `sm` for dense inline contexts, `lg` for prominent, headline-adjacent placements. Note that `size` also flips the label weight (bold below `lg`).\n",
|
|
19033
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-mention>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Inline Mention\n\nThe canonical form. Provide `label` with the user handle or display name. The component renders the default `@` glyph; the mention is read-only until `deletable` is set.\n\n```html\n<mds-text>\n Ciao <mds-mention label=\"mario.rossi\"></mds-mention>, sei riuscito a inviare il messaggio?\n</mds-text>\n```\n\n#### Removable Mention\n\nSet `deletable` to show the remove button, then listen for `mdsMentionDelete` on the element. The\nevent carries the mention that was dismissed, so one handler can serve a whole list.\n\n```html\n<mds-mention id=\"m1\" label=\"mario.rossi\" deletable></mds-mention>\n<script>\n document.querySelector('#m1').addEventListener('mdsMentionDelete', ({ detail }) => {\n detail.element.remove();\n });\n</script>\n```\n\n#### Custom Icon\n\nOverride the default `@` glyph with any Magma icon slug via the `icon` prop. Use this when the mention refers to a team, group, or entity that has a dedicated icon.\n\n```html\n<mds-mention label=\"team-design\" icon=\"mi/baseline/group\"></mds-mention>\n```\n\n#### Sizing\n\nUse the `size` prop to match the mention's visual weight to its context. `sm` is the default for dense inline use; `md` scales up the icon and typography; `lg` uses headline-weight typography for prominent placements.\n\n```html\n<!-- Dense list or comment thread -->\n<mds-mention label=\"anna.verdi\" size=\"sm\"></mds-mention>\n\n<!-- Standard body text -->\n<mds-mention label=\"anna.verdi\" size=\"md\"></mds-mention>\n\n<!-- Heading-adjacent or featured mention -->\n<mds-mention label=\"anna.verdi\" size=\"lg\"></mds-mention>\n```\n\n#### Mention Inside a Comment or Message\n\nPlace `<mds-mention>` inline within `<mds-text>` to embed it naturally in body copy, preserving vertical alignment.\n\n```html\n<mds-text>\n Il documento e' stato approvato da\n <mds-mention label=\"lucia.ferrari\" icon=\"mi/baseline/person\"></mds-mention>\n e sara' pubblicato domani.\n</mds-text>\n```\n\n#### Multiple Mentions in One Sentence\n\nDrop several `<mds-mention>` tokens in the same text flow. Each is a self-contained pill; they line-wrap independently.\n\n```html\n<mds-text>\n <mds-mention label=\"marco.bianchi\"></mds-mention> e\n <mds-mention label=\"giulia.conti\"></mds-mention>\n sono stati assegnati alla revisione.\n</mds-text>\n```\n\n#### Styling Customization\n\nAdjust the icon size through the documented `--mds-mention-icon-size` CSS custom property. Set it on the host element or a parent selector; use Magma spacing tokens to stay on the design grid.\n\n```css\n.featured-comment mds-mention {\n --mds-mention-icon-size: var(--spacing-700);\n}\n```\n",
|
|
19034
|
+
"3. Antipattern": "Common incorrect uses of `<mds-mention>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Slot Content Into the Component\n\n`<mds-mention>` has no default slot and no named slots. Any child nodes placed inside the tag are silently ignored. Pass all content through the `label` and `icon` props.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-mention>\n <mds-icon name=\"mi/baseline/person\"></mds-icon>\n mario.rossi\n</mds-mention>\n\n<!-- ✅ CORRECT -->\n<mds-mention label=\"mario.rossi\" icon=\"mi/baseline/person\"></mds-mention>\n```\n\n#### Do Not Use a Raw `<span>` Chip Instead of the Component\n\nWrapping text in a styled `<span>` misses the remove affordance, icon handling, size ramp, and dark-mode token cascade. Use `<mds-mention>` whenever the UI needs an @-mention token.\n\n```html\n<!-- 🚫 INCORRECT -->\n<span class=\"pill\">@mario.rossi</span>\n\n<!-- ✅ CORRECT -->\n<mds-mention label=\"mario.rossi\"></mds-mention>\n```\n\n#### Do Not Override Size with Inline CSS\n\nThe `size` prop drives icon dimensions, padding, and typography together as a coordinated unit. Setting `font-size`, `width`, or `height` inline breaks that coordination and can misalign the icon and label.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-mention label=\"anna.verdi\" style=\"font-size: 20px; height: 40px;\"></mds-mention>\n\n<!-- ✅ CORRECT -->\n<mds-mention label=\"anna.verdi\" size=\"lg\"></mds-mention>\n```\n\n#### Do Not Customize Style by Piercing the Shadow DOM\n\nThe only supported customization surface is `--mds-mention-icon-size`. Targeting internal elements via `>>>`, `/deep/`, or undocumented `::part()` names couples your code to implementation details and will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-mention >>> mds-icon {\n width: 32px;\n}\n\n/* ✅ CORRECT */\nmds-mention {\n --mds-mention-icon-size: var(--spacing-700);\n}\n```\n\n#### Do Not Listen for `click` on the Remove Button Directly\n\nThe remove button lives inside the shadow DOM: a `click` listener on the host cannot tell it apart\nfrom a click on the label, and reaching into the shadow root ties your code to an internal class\nname. Listen for `mdsMentionDelete` instead - it is the contract, and it names the mention that was\ndismissed.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-mention id=\"m1\" label=\"marco.bianchi\" deletable></mds-mention>\n<script>\n document.querySelector('#m1').addEventListener('click', removeMention);\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-mention id=\"m1\" label=\"marco.bianchi\" deletable></mds-mention>\n<script>\n document.querySelector('#m1').addEventListener('mdsMentionDelete', removeMention);\n</script>\n```\n"
|
|
19204
19035
|
},
|
|
19205
19036
|
"props": [
|
|
19037
|
+
{
|
|
19038
|
+
"name": "deletable",
|
|
19039
|
+
"type": "boolean | undefined",
|
|
19040
|
+
"complexType": {
|
|
19041
|
+
"original": "boolean",
|
|
19042
|
+
"resolved": "boolean | undefined",
|
|
19043
|
+
"references": {}
|
|
19044
|
+
},
|
|
19045
|
+
"mutable": false,
|
|
19046
|
+
"attr": "deletable",
|
|
19047
|
+
"reflectToAttr": true,
|
|
19048
|
+
"docs": "Shows the cross icon to perform cancel/delete action on element",
|
|
19049
|
+
"docsTags": [],
|
|
19050
|
+
"values": [
|
|
19051
|
+
{
|
|
19052
|
+
"type": "boolean"
|
|
19053
|
+
},
|
|
19054
|
+
{
|
|
19055
|
+
"type": "undefined"
|
|
19056
|
+
}
|
|
19057
|
+
],
|
|
19058
|
+
"optional": true,
|
|
19059
|
+
"required": false,
|
|
19060
|
+
"getter": false,
|
|
19061
|
+
"setter": false
|
|
19062
|
+
},
|
|
19206
19063
|
{
|
|
19207
19064
|
"name": "icon",
|
|
19208
19065
|
"type": "string | undefined",
|
|
@@ -19305,7 +19162,29 @@
|
|
|
19305
19162
|
}
|
|
19306
19163
|
],
|
|
19307
19164
|
"methods": [],
|
|
19308
|
-
"events": [
|
|
19165
|
+
"events": [
|
|
19166
|
+
{
|
|
19167
|
+
"event": "mdsMentionDelete",
|
|
19168
|
+
"detail": "MdsMentionEvent",
|
|
19169
|
+
"bubbles": true,
|
|
19170
|
+
"complexType": {
|
|
19171
|
+
"original": "MdsMentionEvent",
|
|
19172
|
+
"resolved": "MdsMentionEvent",
|
|
19173
|
+
"references": {
|
|
19174
|
+
"MdsMentionEvent": {
|
|
19175
|
+
"location": "import",
|
|
19176
|
+
"path": "./meta/interface",
|
|
19177
|
+
"id": "src/components/mds-mention/meta/interface.ts::MdsMentionEvent",
|
|
19178
|
+
"referenceLocation": "MdsMentionEvent"
|
|
19179
|
+
}
|
|
19180
|
+
}
|
|
19181
|
+
},
|
|
19182
|
+
"cancelable": true,
|
|
19183
|
+
"composed": true,
|
|
19184
|
+
"docs": "Emits when the component's delete button is clicked",
|
|
19185
|
+
"docsTags": []
|
|
19186
|
+
}
|
|
19187
|
+
],
|
|
19309
19188
|
"listeners": [],
|
|
19310
19189
|
"styles": [
|
|
19311
19190
|
{
|
|
@@ -19370,10 +19249,36 @@
|
|
|
19370
19249
|
],
|
|
19371
19250
|
"usage": {
|
|
19372
19251
|
"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 closes the modal; with `interaction=\"strict\"` 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 the 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. 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",
|
|
19373
|
-
"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 overlay conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.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('mdsButtonClick', () => { 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-tone-neutral shadow-
|
|
19252
|
+
"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 overlay conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.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('mdsButtonClick', () => { 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-tone-neutral 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 name=\"nome\" label=\"Nome\"></mds-input>\n <mds-input name=\"cognome\" label=\"Cognome\"></mds-input>\n </div>\n\n <footer slot=\"bottom\" class=\"p-400 flex gap-300 justify-end bg-tone-neutral 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 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('mdsButtonClick', () => {\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 id=\"input-ricerca\" label=\"Cerca\"></mds-input>\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 white window surface and the close button). The slotted element receives `role=\"dialog\"` automatically. 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=\"actions\" variant=\"primary\" tone=\"text\">Annulla</mds-button>\n <mds-button slot=\"actions\" 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 at runtime\ndocument.getElementById('pannello-info').hideBackdrop = true;\n```\n\n#### CSS Customization\n\nStyle the window surface only through the documented `--mds-modal-*` CSS custom properties. Set them on the host element.\n\n```css\n/* Rounded card-style center modal */\n#modal-card {\n --mds-modal-window-radius: var(--radius-xl);\n --mds-modal-window-distance: var(--spacing-600);\n --mds-modal-window-overflow: hidden;\n --mds-modal-window-background: rgb(var(--tone-neutral));\n --mds-modal-window-shadow: var(--shadow-2xl);\n --mds-modal-window-max-width: 480px;\n}\n\n/* Full-width drawer */\n#drawer-bottom {\n --mds-modal-window-radius: var(--radius-lg) var(--radius-lg) 0 0;\n --mds-modal-window-max-width: 100%;\n --mds-modal-window-min-width: 100%;\n}\n```\n",
|
|
19374
19253
|
"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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Set `opened=\"false\"` to Close the Modal\n\nBoolean props in Stencil treat any non-empty string as truthy. Setting `opened=\"false\"` keeps the modal open instead of closing it. Remove the attribute or set the prop to `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```javascript\n// 🚫 INCORRECT\nmodal.opened = false;\n\n// ✅ CORRECT\nmodal.opened = undefined;\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-tone-neutral\">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 `--mds-modal-*` CSS custom properties and the two documented shadow parts (`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-background: rgb(var(--tone-neutral));\n --mds-modal-window-radius: var(--radius-xl);\n --mds-modal-window-distance: 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 `interaction=\"strict\"` will silently break your handler.\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 Skip the `close()` Method When Dismissing Programmatically from Strict Modals\n\nWhen `interaction=\"strict\"` is set, the internal `closeModal` guard prevents backdrop-click dismissal. Manually setting `opened = undefined` bypasses the guard but skips the `mdsModalClose` event and animation teardown. Use the `close()` method instead.\n\n```javascript\n// 🚫 INCORRECT (skips event emission when interaction=\"strict\")\ndocument.getElementById('modal-strict').opened = undefined;\n\n// ✅ CORRECT\nawait document.getElementById('modal-strict').close();\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"
|
|
19375
19254
|
},
|
|
19376
19255
|
"props": [
|
|
19256
|
+
{
|
|
19257
|
+
"name": "accessibleName",
|
|
19258
|
+
"type": "string | undefined",
|
|
19259
|
+
"complexType": {
|
|
19260
|
+
"original": "string",
|
|
19261
|
+
"resolved": "string | undefined",
|
|
19262
|
+
"references": {}
|
|
19263
|
+
},
|
|
19264
|
+
"mutable": false,
|
|
19265
|
+
"attr": "aria-label",
|
|
19266
|
+
"reflectToAttr": false,
|
|
19267
|
+
"docs": "The accessible name of the modal: the name a screen reader announces when the window\nopens. The `<dialog>` this component renders is the dialog, so the name goes there.",
|
|
19268
|
+
"docsTags": [],
|
|
19269
|
+
"values": [
|
|
19270
|
+
{
|
|
19271
|
+
"type": "string"
|
|
19272
|
+
},
|
|
19273
|
+
{
|
|
19274
|
+
"type": "undefined"
|
|
19275
|
+
}
|
|
19276
|
+
],
|
|
19277
|
+
"optional": true,
|
|
19278
|
+
"required": false,
|
|
19279
|
+
"getter": false,
|
|
19280
|
+
"setter": false
|
|
19281
|
+
},
|
|
19377
19282
|
{
|
|
19378
19283
|
"name": "animation",
|
|
19379
19284
|
"type": "\"3d\" | \"custom\" | \"slide\" | undefined",
|
|
@@ -19992,30 +19897,7 @@
|
|
|
19992
19897
|
"setter": false
|
|
19993
19898
|
}
|
|
19994
19899
|
],
|
|
19995
|
-
"methods": [
|
|
19996
|
-
{
|
|
19997
|
-
"name": "updateLang",
|
|
19998
|
-
"returns": {
|
|
19999
|
-
"type": "Promise<void>",
|
|
20000
|
-
"docs": ""
|
|
20001
|
-
},
|
|
20002
|
-
"complexType": {
|
|
20003
|
-
"signature": "() => Promise<void>",
|
|
20004
|
-
"parameters": [],
|
|
20005
|
-
"references": {
|
|
20006
|
-
"Promise": {
|
|
20007
|
-
"location": "global",
|
|
20008
|
-
"id": "global::Promise"
|
|
20009
|
-
}
|
|
20010
|
-
},
|
|
20011
|
-
"return": "Promise<void>"
|
|
20012
|
-
},
|
|
20013
|
-
"signature": "updateLang() => Promise<void>",
|
|
20014
|
-
"parameters": [],
|
|
20015
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
20016
|
-
"docsTags": []
|
|
20017
|
-
}
|
|
20018
|
-
],
|
|
19900
|
+
"methods": [],
|
|
20019
19901
|
"events": [
|
|
20020
19902
|
{
|
|
20021
19903
|
"event": "mdsNoteDelete",
|
|
@@ -20339,7 +20221,7 @@
|
|
|
20339
20221
|
"docs": "This is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.",
|
|
20340
20222
|
"docsTags": [],
|
|
20341
20223
|
"usage": {
|
|
20342
|
-
"1. Description": "The `<mds-paginator>` web component is the page-navigation control of the Magma Design System. It renders a horizontal strip of numbered page items framed by previous/next arrows, replacing an ad-hoc set of links or buttons with a single self-managing control.\n\n#### Semantic Behavior\n\n- **Self-rendered children**: The paginator generates its own page items internally from `pages`; authors do not slot the items.\n- **Page change event**: Selecting a page (or an arrow) emits `mdsPaginatorChange` with a detail of `{ page, caller }`, where `caller` is the `mds-paginator-item` that triggered the change.\n- **Bounds clamping**: Navigation requests below `1` or above `pages` are ignored, so the arrows can never move past the valid range.\n- **Arrow disabling**: The back arrow is disabled on the first page and the forward arrow on the last page.\n- **Auto-scroll into view**: When `pages` exceeds two, the strip scrolls so the active page is centered;
|
|
20224
|
+
"1. Description": "The `<mds-paginator>` web component is the page-navigation control of the Magma Design System. It renders a horizontal strip of numbered page items framed by previous/next arrows, replacing an ad-hoc set of links or buttons with a single self-managing control.\n\n#### Semantic Behavior\n\n- **Self-rendered children**: The paginator generates its own page items internally from `pages`; authors do not slot the items.\n- **Page change event**: Selecting a page (or an arrow) emits `mdsPaginatorChange` with a detail of `{ page, caller }`, where `caller` is the `mds-paginator-item` that triggered the change.\n- **Bounds clamping**: Navigation requests below `1` or above `pages` are ignored, so the arrows can never move past the valid range.\n- **Arrow disabling**: The back arrow is disabled on the first page and the forward arrow on the last page.\n- **Auto-scroll into view**: When `pages` exceeds two, the strip scrolls so the active page is centered; selecting an item re-centers it, and so does focusing an item from the keyboard (tabbing through the pages). Pointer interaction never scrolls the strip before the click lands, so the clicked page is always the one selected. Scroll motion is themeable via `--mds-paginator-scroll-behavior`.\n- **Initial sync**: On load the component navigates to the provided `currentPage`, emitting the change event and scrolling the strip to match.\n\n#### Properties & Visual Configurations\n\n- **`pages`** is the total number of pages the control should represent and drives how many items are rendered; with `0` only the arrows appear.\n- **`currentPage`** marks which item is selected and which arrows are disabled; set it to control the paginator from outside, or read it back after a `mdsPaginatorChange` to follow user navigation.\n\nThis component does not use the shared `variant` / `tone` ladders defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); its appearance is tuned only through the CSS custom properties documented in `readme.md`.\n",
|
|
20343
20225
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-paginator>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Paginator\n\nProvide `pages` with the total number of pages. The component renders all items and the previous/next arrows automatically. The `pages` prop is all that is required for a working paginator.\n\n```html\n<mds-paginator pages=\"20\"></mds-paginator>\n```\n\n#### Starting on a Specific Page\n\nSet `current-page` to pre-select an initial page. On load the component emits `mdsPaginatorChange` and scrolls the strip to center the active item.\n\n```html\n<mds-paginator pages=\"32\" current-page=\"16\"></mds-paginator>\n```\n\n#### Listening to Page Changes\n\nListen for `mdsPaginatorChange` to react to navigation. The event detail carries `{ page, caller }` where `page` is the newly selected page number and `caller` is the `mds-paginator-item` that triggered the change.\n\n```html\n<mds-paginator id=\"pager\" pages=\"10\"></mds-paginator>\n\n<script>\n document.getElementById('pager').addEventListener('mdsPaginatorChange', (e) => {\n const nuovaPagina = e.detail.page;\n // Aggiorna la tabella o la lista con i dati della nuova pagina\n caricaDati(nuovaPagina);\n });\n</script>\n```\n\n#### Controlled Navigation from Outside\n\nWrite `current-page` programmatically to drive the paginator from application state - for example when a search resets pagination to page 1.\n\n```html\n<mds-paginator id=\"pager\" pages=\"15\" current-page=\"1\"></mds-paginator>\n\n<script>\n function resettaPaginazione() {\n document.getElementById('pager').currentPage = 1;\n }\n</script>\n```\n\n#### Single-Page and Two-Page Edge Cases\n\nWhen `pages` is `1` only the first/last item and the arrows appear (the scrollable strip is omitted). When `pages` is `2` both the first and last items render without the strip. Both are valid states - pass the real page count without special-casing.\n\n```html\n<!-- Una sola pagina: solo gli arrow e la pagina 1 -->\n<mds-paginator pages=\"1\"></mds-paginator>\n\n<!-- Due pagine: pagina 1 e pagina 2, nessuna strip -->\n<mds-paginator pages=\"2\"></mds-paginator>\n```\n\n#### Styling the Page Strip Background\n\nOverride `--mds-paginator-background` on the host to change the background of the scrollable pages area. Use a Magma color token wrapped in `rgb(var(...))` so dark mode keeps working.\n\n```css\n.mia-tabella mds-paginator {\n --mds-paginator-background: rgb(var(--tone-neutral-08));\n}\n```\n\n#### Disabling Scroll Animation\n\nSet `--mds-paginator-scroll-behavior` to `auto` to remove the animated scroll when jumping between pages - useful for contexts that already honour `prefers-reduced-motion` at application level.\n\n```css\n.stampa mds-paginator {\n --mds-paginator-scroll-behavior: auto;\n}\n```\n\n#### Styling Individual Items\n\nThe child `mds-paginator-item` component exposes its own `--mds-paginator-item-*` custom properties. Set them on the `mds-paginator` host or a parent selector; they cascade into the shadow-rendered items.\n\n```css\n.paginatore-compatto mds-paginator {\n --mds-paginator-item-size: 28px;\n --mds-paginator-item-radius: var(--radius-sm);\n --mds-paginator-item-background-selected: rgb(var(--variant-primary-03));\n --mds-paginator-item-color-selected: rgb(var(--tone-kaolin-10));\n}\n```\n",
|
|
20344
20226
|
"3. Antipattern": "Common incorrect uses of `<mds-paginator>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Slot `mds-paginator-item` Manually\n\n`<mds-paginator>` generates all its child items from the `pages` prop and accepts no slots. Manually adding `<mds-paginator-item>` children has no effect and produces duplicate or broken controls.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-paginator pages=\"5\">\n <mds-paginator-item selected>3</mds-paginator-item>\n</mds-paginator>\n\n<!-- ✅ CORRECT -->\n<mds-paginator pages=\"5\" current-page=\"3\"></mds-paginator>\n```\n\n#### Do Not Use `mds-paginator-item` Outside `mds-paginator`\n\n`<mds-paginator-item>` is an internal sub-part. Its `disabled`, `selected`, and `icon` props are managed exclusively by the parent. Using it standalone produces unstyled, non-functional controls.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-paginator-item>1</mds-paginator-item>\n<mds-paginator-item selected>2</mds-paginator-item>\n\n<!-- ✅ CORRECT -->\n<mds-paginator pages=\"5\" current-page=\"2\"></mds-paginator>\n```\n\n#### Do Not Set `pages` to Zero to \"Hide\" the Paginator\n\nWhen `pages` is `0` only the two arrows render, which is visually incomplete and confusing. To conditionally hide the paginator, remove it from the DOM entirely or set `display: none` on the host.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-paginator pages=\"0\"></mds-paginator>\n\n<!-- ✅ CORRECT -->\n<mds-paginator v-if=\"totalePagine > 0\" :pages=\"totalePagine\"></mds-paginator>\n```\n\n#### Do Not Listen for Native `click` to Detect Page Changes\n\nThe native `click` event fires on the internal shadow items and may not bubble as expected. Use the documented `mdsPaginatorChange` event instead, which carries the selected page number in `event.detail.page`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-paginator id=\"pager\" pages=\"10\"></mds-paginator>\n<script>\n document.getElementById('pager').addEventListener('click', (e) => {\n // detail.page is undefined - this is the wrong event\n console.log(e.detail?.page);\n });\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-paginator id=\"pager\" pages=\"10\"></mds-paginator>\n<script>\n document.getElementById('pager').addEventListener('mdsPaginatorChange', (e) => {\n console.log(e.detail.page);\n });\n</script>\n```\n\n#### Do Not Set `current-page` to a String\n\n`current-page` is a numeric prop. Passing a quoted string (common in plain HTML attribute authoring) forces a type coercion that can produce unexpected scroll and selection behavior.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-paginator pages=\"20\" current-page=\"5\"></mds-paginator>\n<!-- The attribute form is fine; the anti-pattern is framework bindings that pass a string -->\n\n<!-- 🚫 INCORRECT (framework binding passing a string, not a number) -->\n<!-- <mds-paginator :pages=\"20\" :current-page=\"'5'\"></mds-paginator> -->\n\n<!-- ✅ CORRECT (bind the number directly) -->\n<!-- <mds-paginator :pages=\"20\" :current-page=\"5\"></mds-paginator> -->\n```\n\n#### Do Not Pierce Shadow DOM to Style Items\n\nInternal `mds-paginator-item` elements live in shadow DOM. Targeting them with `>>>`, `/deep/`, or unrecognised `::part()` names breaks on any release. Use the documented `--mds-paginator-*` and `--mds-paginator-item-*` CSS custom properties on the host instead.\n\n```css\n/* 🚫 INCORRECT */\nmds-paginator >>> mds-paginator-item {\n border-radius: 4px;\n}\n\n/* ✅ CORRECT */\nmds-paginator {\n --mds-paginator-item-radius: var(--radius-sm);\n --mds-paginator-item-background-selected: rgb(var(--variant-primary-03));\n}\n```\n"
|
|
20345
20227
|
},
|
|
@@ -20821,30 +20703,7 @@
|
|
|
20821
20703
|
"setter": false
|
|
20822
20704
|
}
|
|
20823
20705
|
],
|
|
20824
|
-
"methods": [
|
|
20825
|
-
{
|
|
20826
|
-
"name": "updateLang",
|
|
20827
|
-
"returns": {
|
|
20828
|
-
"type": "Promise<void>",
|
|
20829
|
-
"docs": ""
|
|
20830
|
-
},
|
|
20831
|
-
"complexType": {
|
|
20832
|
-
"signature": "() => Promise<void>",
|
|
20833
|
-
"parameters": [],
|
|
20834
|
-
"references": {
|
|
20835
|
-
"Promise": {
|
|
20836
|
-
"location": "global",
|
|
20837
|
-
"id": "global::Promise"
|
|
20838
|
-
}
|
|
20839
|
-
},
|
|
20840
|
-
"return": "Promise<void>"
|
|
20841
|
-
},
|
|
20842
|
-
"signature": "updateLang() => Promise<void>",
|
|
20843
|
-
"parameters": [],
|
|
20844
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
20845
|
-
"docsTags": []
|
|
20846
|
-
}
|
|
20847
|
-
],
|
|
20706
|
+
"methods": [],
|
|
20848
20707
|
"events": [],
|
|
20849
20708
|
"listeners": [],
|
|
20850
20709
|
"styles": [],
|
|
@@ -20941,17 +20800,17 @@
|
|
|
20941
20800
|
},
|
|
20942
20801
|
{
|
|
20943
20802
|
"name": "slot",
|
|
20944
|
-
"text": "- Add `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-language`, or `mds-pref-
|
|
20803
|
+
"text": "- Add `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-language`, or `mds-pref-mode` element/s."
|
|
20945
20804
|
},
|
|
20946
20805
|
{
|
|
20947
20806
|
"name": "example",
|
|
20948
|
-
"text": "<mds-pref>\n<mds-pref-animation></mds-pref-animation>\n<mds-pref-consumption></mds-pref-consumption>\n<mds-pref-contrast></mds-pref-contrast>\n<mds-pref-
|
|
20807
|
+
"text": "<mds-pref>\n<mds-pref-animation></mds-pref-animation>\n<mds-pref-consumption></mds-pref-consumption>\n<mds-pref-contrast></mds-pref-contrast>\n<mds-pref-mode></mds-pref-mode>\n<mds-pref-language>\n<mds-pref-language-item code=\"it\"></mds-pref-language-item>\n<mds-pref-language-item code=\"en\"></mds-pref-language-item>\n</mds-pref-language>\n</mds-pref>"
|
|
20949
20808
|
}
|
|
20950
20809
|
],
|
|
20951
20810
|
"usage": {
|
|
20952
|
-
"1. Description": "The `<mds-pref>` web component is the accessibility-preferences panel of the Magma Design System: a compound parent that groups user-facing settings (animation, consumption, contrast, theme, language) so people can tune readability, motion, and language for their session. It acts as the coordinator for the `mds-pref-*` children slotted inside it.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-
|
|
20953
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Full Preferences Panel\n\nThe canonical form: slot every `mds-pref-*` control directly inside `<mds-pref>`. The parent coordinates size propagation and the reload notice automatically - no extra wiring is needed.\n\n```html\n<mds-pref>\n <mds-pref-
|
|
20954
|
-
"3. Antipattern": "Common incorrect uses of `<mds-pref>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Place Non-Pref Children in the Default Slot\n\nThe default slot accepts only `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-language`, and `mds-pref-
|
|
20811
|
+
"1. Description": "The `<mds-pref>` web component is the accessibility-preferences panel of the Magma Design System: a compound parent that groups user-facing settings (animation, consumption, contrast, theme, language) so people can tune readability, motion, and language for their session. It acts as the coordinator for the `mds-pref-*` children slotted inside it.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-mode`, and/or `mds-pref-language` children in its default slot; it owns no preference UI of its own beyond coordination.\n- **Size propagation**: Changing `size` cascades the value down to every nested `mds-pref-*` child, keeping the whole panel on one tab size.\n- **Reload notice**: Listens for the `mdsPrefChange` event from children and, when the changed preference cannot apply live (`consumption` or `language`), reveals an inline caption prompting the user to refresh the page.\n- **Live language sync**: When a `language` change is emitted, the panel re-resolves its own locale so the reload notice is shown in the newly selected language.\n\n#### Properties & Visual Configurations\n\n`size` is one of the shared tab sizes and is forwarded to children rather than styling the host directly - set it once on the parent instead of on each child.\n\n#### Other behavioral props\n\n- **`controller`** switches the component from a visible on-DOM panel into a headless controller that applies and reacts to preferences without rendering UI; in this mode it drives document-level preference state without a visible panel.\n",
|
|
20812
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Full Preferences Panel\n\nThe canonical form: slot every `mds-pref-*` control directly inside `<mds-pref>`. The parent coordinates size propagation and the reload notice automatically - no extra wiring is needed.\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-theme>\n <mds-pref-theme-item name=\"default\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"magma\"></mds-pref-theme-item>\n </mds-pref-theme>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Partial Panel - Subset of Controls\n\nSlot only the controls your application needs. `<mds-pref>` renders whatever children are present; omitted controls are simply absent.\n\n```html\n<!-- Accessibility-only panel: contrast and animation controls -->\n<mds-pref>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Controlling Size\n\nUse the `size` prop on the parent to drive all child controls at once. Setting it on each child individually is unnecessary - the parent propagates the value automatically.\n\n```html\n<!-- Compact panel for a sidebar or popover -->\n<mds-pref size=\"sm\">\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Headless Controller Mode\n\nSet the `controller` boolean attribute when you need the preference engine to apply saved preferences from `localStorage` on page load without rendering any visible UI. The host is hidden via CSS (`display: none`) and still activates all child preference controls.\n\n```html\n<!-- Place in <body>; the panel is invisible but activates stored preferences -->\n<mds-pref controller>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Language Selector with Multiple Languages\n\n`<mds-pref-language>` requires its child `<mds-pref-language-item>` elements to be present; the items are not self-generating. Pass language codes supported by your application.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Reload Notice Handling\n\nWhen a user changes `consumption` or `language`, `<mds-pref>` automatically shows an inline caption telling the user to refresh the page - no extra code needed. Verify that your page does not suppress this notice with CSS overrides.\n\n```html\n<!-- The reload notice appears automatically inside the shadow root;\n do not try to inject your own reload banner outside the component -->\n<mds-pref>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n",
|
|
20813
|
+
"3. Antipattern": "Common incorrect uses of `<mds-pref>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Place Non-Pref Children in the Default Slot\n\nThe default slot accepts only `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-language`, and `mds-pref-mode` children. Slotting other elements breaks the coordination logic and may not render.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref>\n <div class=\"custom-section\">Tema</div>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n\n<!-- ✅ CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Use `mds-pref-*` Children Outside `<mds-pref>`\n\nPreference children depend on parent coordination for size propagation and the reload notice. Using them standalone removes that orchestration.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-contrast></mds-pref-contrast>\n<mds-pref-animation></mds-pref-animation>\n\n<!-- ✅ CORRECT -->\n<mds-pref>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Do Not Set `controller=\"false\"` to Turn Off Controller Mode\n\n`controller` is a boolean attribute. Setting it to the string `\"false\"` still evaluates as truthy in HTML and keeps the panel hidden. Remove the attribute entirely to switch back to visible mode.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref controller=\"false\">\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n\n<!-- ✅ CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Set `size` on Each Child Individually\n\n`<mds-pref>` propagates the `size` prop to all its `mds-pref-*` children automatically via `handleSizeChange`. Setting `size` on every child is redundant and will be overwritten by any later change to the parent prop.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref>\n <mds-pref-mode size=\"sm\"></mds-pref-mode>\n <mds-pref-contrast size=\"sm\"></mds-pref-contrast>\n <mds-pref-animation size=\"sm\"></mds-pref-animation>\n</mds-pref>\n\n<!-- ✅ CORRECT -->\n<mds-pref size=\"sm\">\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Do Not Listen for the Native `change` Event to Detect Preference Changes\n\nNative events may not bubble out of shadow DOM as expected. Use the documented `mdsPrefChange` event emitted by each `mds-pref-*` child.\n\n```html\n<!-- 🚫 INCORRECT -->\n<script>\n document.querySelector('mds-pref').addEventListener('change', (e) => {\n console.log(e);\n });\n</script>\n\n<!-- ✅ CORRECT -->\n<script>\n document.querySelector('mds-pref-mode').addEventListener('mdsPrefChange', (e) => {\n console.log(e.detail.preference);\n });\n</script>\n```\n\n#### Do Not Add a Custom Reload Banner Alongside the Panel\n\n`<mds-pref>` already renders an inline reload caption in its shadow root when `consumption` or `language` changes. Duplicating this with an external banner leads to double messaging.\n\n```html\n<!-- 🚫 INCORRECT -->\n<div id=\"reload-hint\" hidden>Ricarica la pagina per applicare le modifiche.</div>\n<mds-pref>\n <mds-pref-consumption></mds-pref-consumption>\n</mds-pref>\n<script>\n document.querySelector('mds-pref-consumption').addEventListener('mdsPrefChange', () => {\n document.getElementById('reload-hint').hidden = false;\n });\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-pref>\n <mds-pref-consumption></mds-pref-consumption>\n</mds-pref>\n```\n"
|
|
20955
20814
|
},
|
|
20956
20815
|
"props": [
|
|
20957
20816
|
{
|
|
@@ -21019,37 +20878,14 @@
|
|
|
21019
20878
|
"setter": false
|
|
21020
20879
|
}
|
|
21021
20880
|
],
|
|
21022
|
-
"methods": [
|
|
21023
|
-
{
|
|
21024
|
-
"name": "updateLang",
|
|
21025
|
-
"returns": {
|
|
21026
|
-
"type": "Promise<void>",
|
|
21027
|
-
"docs": ""
|
|
21028
|
-
},
|
|
21029
|
-
"complexType": {
|
|
21030
|
-
"signature": "() => Promise<void>",
|
|
21031
|
-
"parameters": [],
|
|
21032
|
-
"references": {
|
|
21033
|
-
"Promise": {
|
|
21034
|
-
"location": "global",
|
|
21035
|
-
"id": "global::Promise"
|
|
21036
|
-
}
|
|
21037
|
-
},
|
|
21038
|
-
"return": "Promise<void>"
|
|
21039
|
-
},
|
|
21040
|
-
"signature": "updateLang() => Promise<void>",
|
|
21041
|
-
"parameters": [],
|
|
21042
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
21043
|
-
"docsTags": []
|
|
21044
|
-
}
|
|
21045
|
-
],
|
|
20881
|
+
"methods": [],
|
|
21046
20882
|
"events": [],
|
|
21047
20883
|
"listeners": [],
|
|
21048
20884
|
"styles": [],
|
|
21049
20885
|
"slots": [
|
|
21050
20886
|
{
|
|
21051
20887
|
"name": "",
|
|
21052
|
-
"docs": "Add `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-language`, or `mds-pref-
|
|
20888
|
+
"docs": "Add `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-language`, or `mds-pref-mode` element/s."
|
|
21053
20889
|
}
|
|
21054
20890
|
],
|
|
21055
20891
|
"parts": [],
|
|
@@ -21073,7 +20909,7 @@
|
|
|
21073
20909
|
"docsTags": [],
|
|
21074
20910
|
"usage": {
|
|
21075
20911
|
"1. Description": "The `<mds-pref-animation>` web component is a preference control that lets users choose how animations are presented (reduced, system-driven, or fully enabled). It is a compound child of [`<mds-pref>`](../../mds-pref) and renders a labelled three-option tab group rather than any native HTML primitive.\n\n#### Semantic Behavior\n\n- **Compound child constraint**: Must be placed as a direct default-slot child of `<mds-pref>`; it is not used standalone or mixed into other containers.\n- **Tab-group selection**: Renders three options (reduce / system / no-preference); the active one is driven by the `mode` value, and clicking an option sets that mode.\n- **Applies the preference globally**: Choosing a mode applies it across the whole document and persists the choice, so it is restored on later visits.\n- **Initial mode resolution**: The effective mode is resolved in order from the `mode` prop, then the persisted value, then the `system` default.\n- **Change event**: `mdsPrefChange` (detail `{ preference: 'animation' }`) fires on every selection; the parent `<mds-pref>` listens for this to coordinate cross-preference behavior such as the reload-required hint.\n\n#### Properties & Visual Configurations\n\n- **`mode`**: Sets which animation preference is active - `reduce` to suppress motion, `no-preference` to fully enable animations, or `system` to defer to the user's OS setting. Leave unset to fall back to the persisted or default (`system`) value.\n- **`size`**: Sizes the nested tab items (`sm` or `md`). It is normally not set directly; the parent `<mds-pref>` propagates its own `size` down to every `mds-pref-*` child, so set it on the parent for a consistent group.\n",
|
|
21076
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref-animation>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Default Usage Inside `mds-pref`\n\nThe standard form. Place `<mds-pref-animation>` as a direct slot child of [`<mds-pref>`](../../mds-pref). No `mode` or `size` is required - the component restores the last persisted choice and defaults to `system` on a first visit.\n\n```html\n<mds-pref>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Combined Preferences Panel\n\nPlace multiple `mds-pref-*` children inside the same `<mds-pref>`. The parent propagates `size` and coordinates the reload hint.\n\n```html\n<mds-pref>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-
|
|
20912
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref-animation>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Default Usage Inside `mds-pref`\n\nThe standard form. Place `<mds-pref-animation>` as a direct slot child of [`<mds-pref>`](../../mds-pref). No `mode` or `size` is required - the component restores the last persisted choice and defaults to `system` on a first visit.\n\n```html\n<mds-pref>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Combined Preferences Panel\n\nPlace multiple `mds-pref-*` children inside the same `<mds-pref>`. The parent propagates `size` and coordinates the reload hint.\n\n```html\n<mds-pref>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-consumption></mds-pref-consumption>\n</mds-pref>\n```\n\n#### Pre-selecting a Mode via `mode`\n\nPass `mode` to override the persisted value and start from a known state - for example, a first-run onboarding screen that starts with reduced motion.\n\n```html\n<mds-pref>\n <mds-pref-animation mode=\"reduce\"></mds-pref-animation>\n</mds-pref>\n```\n\n#### Listening for Changes\n\nHandle `mdsPrefChange` when the host application needs to react - for example, to announce the new setting or trigger a soft refresh.\n\n```html\n<mds-pref id=\"prefs\">\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n\n<script>\n document.getElementById('prefs').addEventListener('mdsPrefChange', (event) => {\n // event.detail.preference === 'animation'\n console.log('Preferenza animazioni aggiornata', event.detail);\n });\n</script>\n```\n\n#### Compact Size\n\nSet `size=\"sm\"` on the parent `<mds-pref>` to shrink the tab items of every `mds-pref-*` child consistently. Set `size` directly on `<mds-pref-animation>` only when the component appears outside the standard panel.\n\n```html\n<!-- Preferred: set once on the parent -->\n<mds-pref size=\"sm\">\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-contrast></mds-pref-contrast>\n</mds-pref>\n\n<!-- Acceptable when used standalone -->\n<mds-pref-animation size=\"sm\"></mds-pref-animation>\n```\n\n#### Silent Controller (Hidden Preference Sync)\n\nWhen a `<mds-pref controller>` element is placed in the DOM, it applies preferences silently without rendering any UI. `<mds-pref-animation>` inside it restores the persisted animation class on `<html>` on load without showing the tab group.\n\n```html\n<!-- Place once, near the root - no UI is rendered -->\n<mds-pref controller>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n",
|
|
21077
20913
|
"3. Antipattern": "Common incorrect uses of `<mds-pref-animation>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use the Component Outside `mds-pref`\n\n`<mds-pref-animation>` is a compound child of [`<mds-pref>`](../../mds-pref). Without the parent, the `size` prop is not propagated and the parent's reload-hint coordination does not fire.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-animation></mds-pref-animation>\n\n<!-- ✅ CORRECT -->\n<mds-pref>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Do Not Turn Off with `mode=\"false\"` or Remove the Attribute to Reset\n\n`mode` is a string union (`reduce | system | no-preference`), not a boolean. Removing it or setting it to an arbitrary string does not disable the component - it silently falls back to `system`, which may differ from the user's intent.\n\n```html\n<!-- 🚫 INCORRECT - not a valid mode value -->\n<mds-pref-animation mode=\"false\"></mds-pref-animation>\n<mds-pref-animation mode=\"none\"></mds-pref-animation>\n\n<!-- ✅ CORRECT - use an explicit valid mode -->\n<mds-pref-animation mode=\"system\"></mds-pref-animation>\n```\n\n#### Do Not Set `size` on Each Child Individually When Using the Panel\n\nThe parent `<mds-pref>` propagates `size` to all `mds-pref-*` children automatically when the `size` prop changes. Setting it on each child creates an inconsistent group if the parent's size ever changes.\n\n```html\n<!-- 🚫 INCORRECT - size set redundantly on each child -->\n<mds-pref>\n <mds-pref-animation size=\"sm\"></mds-pref-animation>\n <mds-pref-contrast size=\"sm\"></mds-pref-contrast>\n</mds-pref>\n\n<!-- ✅ CORRECT - set once on the parent -->\n<mds-pref size=\"sm\">\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-contrast></mds-pref-contrast>\n</mds-pref>\n```\n\n#### Do Not Listen to Raw `change` Events\n\n`<mds-pref-animation>` emits `mdsPrefChange`, not the native `change` event. The native event does not bubble out of the shadow DOM reliably.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref id=\"prefs\">\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n\n<script>\n document.getElementById('prefs').addEventListener('change', handler);\n</script>\n\n<!-- ✅ CORRECT -->\n<script>\n document.getElementById('prefs').addEventListener('mdsPrefChange', handler);\n</script>\n```\n\n#### Do Not Hand-Roll Animation Preference Handling on `<html>`\n\nThe component already applies `pref-animation-reduce`, `pref-animation-system`, or `pref-animation-no-preference` to `<html>` and persists the choice in `localStorage`. Duplicating this logic conflicts with the component's state and causes double-writes.\n\n```css\n/* 🚫 INCORRECT - duplicates the component's own logic */\nhtml.custom-reduce-motion * {\n animation: none !important;\n}\n```\n\n```html\n<!-- ✅ CORRECT - rely on the class the component sets -->\n<!-- The component sets pref-animation-reduce on <html>;\n target that class in your own CSS if needed -->\n```\n\n```css\n/* Extend, do not replace */\nhtml.pref-animation-reduce .my-widget {\n transition: none;\n}\n```\n"
|
|
21078
20914
|
},
|
|
21079
20915
|
"props": [
|
|
@@ -21158,30 +20994,7 @@
|
|
|
21158
20994
|
"setter": false
|
|
21159
20995
|
}
|
|
21160
20996
|
],
|
|
21161
|
-
"methods": [
|
|
21162
|
-
{
|
|
21163
|
-
"name": "updateLang",
|
|
21164
|
-
"returns": {
|
|
21165
|
-
"type": "Promise<void>",
|
|
21166
|
-
"docs": ""
|
|
21167
|
-
},
|
|
21168
|
-
"complexType": {
|
|
21169
|
-
"signature": "() => Promise<void>",
|
|
21170
|
-
"parameters": [],
|
|
21171
|
-
"references": {
|
|
21172
|
-
"Promise": {
|
|
21173
|
-
"location": "global",
|
|
21174
|
-
"id": "global::Promise"
|
|
21175
|
-
}
|
|
21176
|
-
},
|
|
21177
|
-
"return": "Promise<void>"
|
|
21178
|
-
},
|
|
21179
|
-
"signature": "updateLang() => Promise<void>",
|
|
21180
|
-
"parameters": [],
|
|
21181
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
21182
|
-
"docsTags": []
|
|
21183
|
-
}
|
|
21184
|
-
],
|
|
20997
|
+
"methods": [],
|
|
21185
20998
|
"events": [
|
|
21186
20999
|
{
|
|
21187
21000
|
"event": "mdsPrefChange",
|
|
@@ -21326,30 +21139,7 @@
|
|
|
21326
21139
|
"setter": false
|
|
21327
21140
|
}
|
|
21328
21141
|
],
|
|
21329
|
-
"methods": [
|
|
21330
|
-
{
|
|
21331
|
-
"name": "updateLang",
|
|
21332
|
-
"returns": {
|
|
21333
|
-
"type": "Promise<void>",
|
|
21334
|
-
"docs": ""
|
|
21335
|
-
},
|
|
21336
|
-
"complexType": {
|
|
21337
|
-
"signature": "() => Promise<void>",
|
|
21338
|
-
"parameters": [],
|
|
21339
|
-
"references": {
|
|
21340
|
-
"Promise": {
|
|
21341
|
-
"location": "global",
|
|
21342
|
-
"id": "global::Promise"
|
|
21343
|
-
}
|
|
21344
|
-
},
|
|
21345
|
-
"return": "Promise<void>"
|
|
21346
|
-
},
|
|
21347
|
-
"signature": "updateLang() => Promise<void>",
|
|
21348
|
-
"parameters": [],
|
|
21349
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
21350
|
-
"docsTags": []
|
|
21351
|
-
}
|
|
21352
|
-
],
|
|
21142
|
+
"methods": [],
|
|
21353
21143
|
"events": [
|
|
21354
21144
|
{
|
|
21355
21145
|
"event": "mdsPrefChange",
|
|
@@ -21408,8 +21198,8 @@
|
|
|
21408
21198
|
"docs": "",
|
|
21409
21199
|
"docsTags": [],
|
|
21410
21200
|
"usage": {
|
|
21411
|
-
"1. Description": "The `<mds-pref-contrast>` web component is a preference control that lets users switch the application's contrast mode (`more`, `system`, or `no-preference`). It is a compound child of the [`<mds-pref>`](../../mds-pref) panel and renders as a segmented tab of icon options rather than any single native HTML primitive.\n\n#### Semantic Behavior\n\n- **Compound child only**: It is designed to be placed as a direct slot child of `<mds-pref>` alongside the other preference children (`mds-pref-animation`, `mds-pref-consumption`, `mds-pref-language`, `mds-pref-
|
|
21412
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref-contrast>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Inside the Full Preferences Panel\n\nThe canonical form. Slot `<mds-pref-contrast>` directly inside [`<mds-pref>`](../../mds-pref) alongside the other preference controls. The parent panel propagates `size`, coordinates the reload notice, and handles cross-preference communication automatically.\n\n```html\n<mds-pref>\n <mds-pref-
|
|
21201
|
+
"1. Description": "The `<mds-pref-contrast>` web component is a preference control that lets users switch the application's contrast mode (`more`, `system`, or `no-preference`). It is a compound child of the [`<mds-pref>`](../../mds-pref) panel and renders as a segmented tab of icon options rather than any single native HTML primitive.\n\n#### Semantic Behavior\n\n- **Compound child only**: It is designed to be placed as a direct slot child of `<mds-pref>` alongside the other preference children (`mds-pref-animation`, `mds-pref-consumption`, `mds-pref-language`, `mds-pref-mode`); it is not meant to be used standalone or mixed with unrelated element types.\n- **Mode resolution on render**: The active mode is resolved in order from the `mode` prop, the persisted value, then the `system` default, and applied immediately - so it acts on the document even before any user interaction.\n- **Applies the preference globally**: Selecting a mode applies it across the whole document and persists the choice.\n- **System resolution**: When the host environment exposes a `prefers-contrast` media query, that value is consulted to map the OS-level preference onto the design system's contrast tokens.\n- **Change event**: Every mode change emits `mdsPrefChange` with `{ preference: 'contrast' }`; `<mds-pref>` listens for this to coordinate cross-preference behavior such as the reload-required notice.\n\n#### Properties & Visual Configurations\n\n- **`mode`** - the active contrast preference. Leave it unset to let the component restore the last persisted choice or fall back to `system`; set it explicitly (`more`, `system`, `no-preference`) only when the host wants to force a contrast level. Pick `more` for high-contrast output, `no-preference` for the default theme, and `system` to defer to the OS `prefers-contrast` setting.\n- **`size`** - sizes the nested tab items (`sm` / `md`). In practice this is propagated automatically by the parent `<mds-pref>`, which fans its own `size` down to every `mds-pref-*` child, so it rarely needs to be set directly on this component.\n\nThe component does not use the shared `variant` / `tone` ladders documented in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); its visual states are driven entirely by the resolved `mode`.\n",
|
|
21202
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref-contrast>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Inside the Full Preferences Panel\n\nThe canonical form. Slot `<mds-pref-contrast>` directly inside [`<mds-pref>`](../../mds-pref) alongside the other preference controls. The parent panel propagates `size`, coordinates the reload notice, and handles cross-preference communication automatically.\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n</mds-pref>\n```\n\n#### Accessibility-Only Panel\n\nWhen an application exposes only accessibility controls, slot `<mds-pref-contrast>` together with [`<mds-pref-animation>`](../../mds-pref-animation) inside a minimal `<mds-pref>`. Omitted preference controls are simply absent - no extra configuration is required.\n\n```html\n<mds-pref>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Forcing a Contrast Level Programmatically\n\nSet the `mode` prop explicitly when the host application needs to impose a contrast level regardless of the user's last persisted choice. Valid values are `more` (high contrast), `system` (defers to OS `prefers-contrast`), and `no-preference` (design-system default).\n\n```html\n<!-- Force high contrast for a section of the app that requires it -->\n<mds-pref-contrast mode=\"more\"></mds-pref-contrast>\n```\n\n#### Reacting to Contrast Changes\n\nListen for `mdsPrefChange` to act whenever the user switches the contrast mode. The event detail carries `{ preference: 'contrast' }` so a single handler can distinguish between the different preference controls.\n\n```html\n<mds-pref-contrast id=\"contrast-ctrl\"></mds-pref-contrast>\n\n<script>\n document\n .getElementById('contrast-ctrl')\n .addEventListener('mdsPrefChange', (event) => {\n if (event.detail.preference === 'contrast') {\n console.log('Preferenza contrasto aggiornata');\n }\n });\n</script>\n```\n\n#### Controlling Size\n\nUse the `size` prop when rendering `<mds-pref-contrast>` outside `<mds-pref>` and a specific tab-item size is required. Inside `<mds-pref>`, the parent propagates its own `size` automatically - setting it on this child is unnecessary.\n\n```html\n<!-- Compact size for a toolbar or narrow panel -->\n<mds-pref-contrast size=\"sm\"></mds-pref-contrast>\n\n<!-- Default (medium) size - equivalent to omitting the prop -->\n<mds-pref-contrast size=\"md\"></mds-pref-contrast>\n```\n\n#### Restoring the Last Persisted Choice on Page Load\n\nLeave `mode` unset. On every render the component reads `localStorage` for the key `mdsPrefContrast` set during a previous session, falls back to `system` when nothing is stored, and applies the resolved class to `<html>` immediately - no application bootstrap code is needed.\n\n```html\n<!-- mode is intentionally absent: the component self-restores -->\n<mds-pref-contrast></mds-pref-contrast>\n```\n",
|
|
21413
21203
|
"3. Antipattern": "Common incorrect uses of `<mds-pref-contrast>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use Outside Its Parent `<mds-pref>`\n\n`<mds-pref-contrast>` is a compound child designed for direct slot placement inside [`<mds-pref>`](../../mds-pref). Using it standalone in page content bypasses the parent's coordination logic (size propagation, reload notice, cross-preference sequencing).\n\n```html\n<!-- 🚫 INCORRECT -->\n<div class=\"settings-section\">\n <mds-pref-contrast></mds-pref-contrast>\n</div>\n\n<!-- ✅ CORRECT -->\n<mds-pref>\n <mds-pref-contrast></mds-pref-contrast>\n</mds-pref>\n```\n\n#### Do Not Set `size` Directly When Inside `<mds-pref>`\n\nThe parent `<mds-pref>` fans its `size` prop down to every `mds-pref-*` child automatically. Overriding `size` on the child creates a mismatch between sibling controls.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref size=\"md\">\n <mds-pref-contrast size=\"sm\"></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n\n<!-- ✅ CORRECT -->\n<mds-pref size=\"sm\">\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Do Not Pass an Invalid `mode` Value\n\n`mode` accepts only `\"more\"`, `\"system\"`, or `\"no-preference\"`. Passing any other string (e.g. a legacy name or a boolean) silently fails to match any contrast entry and can throw a runtime error when the component tries to apply the CSS class.\n\n```html\n<!-- 🚫 INCORRECT (not a valid ContrastModeType) -->\n<mds-pref-contrast mode=\"high\"></mds-pref-contrast>\n<mds-pref-contrast mode=\"true\"></mds-pref-contrast>\n\n<!-- ✅ CORRECT -->\n<mds-pref-contrast mode=\"more\"></mds-pref-contrast>\n```\n\n#### Do Not Listen for the Native `change` Event\n\nThe component emits the documented `mdsPrefChange` event; there is no native `change` event bubbling out of the shadow DOM. Listening for `change` on the host element will never fire.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-contrast id=\"cp\"></mds-pref-contrast>\n<script>\n document.getElementById('cp').addEventListener('change', handler);\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-pref-contrast id=\"cp\"></mds-pref-contrast>\n<script>\n document.getElementById('cp').addEventListener('mdsPrefChange', handler);\n</script>\n```\n\n#### Do Not Write `@media (prefers-contrast: more)` Overrides in App Code\n\nThe design system manages high-contrast tokens automatically through the `pref-contrast-more` class applied to `<html>` by `<mds-pref-contrast>`. Hand-rolling media query overrides duplicates that logic and breaks when the user picks `system` (OS-driven) vs. `more` (explicit choice), because the two code paths diverge.\n\n```css\n/* 🚫 INCORRECT */\n@media (prefers-contrast: more) {\n .my-card {\n border: 2px solid black;\n }\n}\n\n/* ✅ CORRECT - target the class the component applies */\n:root.pref-contrast-more .my-card,\n:root.pref-contrast-system .my-card {\n border: 2px solid black;\n}\n```\n\n#### Do Not Set `mode=\"false\"` to Reset the Preference\n\nBoolean idioms do not apply here. `mode` is a string union - setting it to `\"false\"` is not a valid value and will not clear the preference. Remove the `mode` attribute entirely (or set the prop to `undefined`) to let the component fall back to the last persisted value.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-contrast mode=\"false\"></mds-pref-contrast>\n\n<!-- ✅ CORRECT (omit mode or unset it programmatically) -->\n<mds-pref-contrast></mds-pref-contrast>\n```\n"
|
|
21414
21204
|
},
|
|
21415
21205
|
"props": [
|
|
@@ -21494,30 +21284,7 @@
|
|
|
21494
21284
|
"setter": false
|
|
21495
21285
|
}
|
|
21496
21286
|
],
|
|
21497
|
-
"methods": [
|
|
21498
|
-
{
|
|
21499
|
-
"name": "updateLang",
|
|
21500
|
-
"returns": {
|
|
21501
|
-
"type": "Promise<void>",
|
|
21502
|
-
"docs": ""
|
|
21503
|
-
},
|
|
21504
|
-
"complexType": {
|
|
21505
|
-
"signature": "() => Promise<void>",
|
|
21506
|
-
"parameters": [],
|
|
21507
|
-
"references": {
|
|
21508
|
-
"Promise": {
|
|
21509
|
-
"location": "global",
|
|
21510
|
-
"id": "global::Promise"
|
|
21511
|
-
}
|
|
21512
|
-
},
|
|
21513
|
-
"return": "Promise<void>"
|
|
21514
|
-
},
|
|
21515
|
-
"signature": "updateLang() => Promise<void>",
|
|
21516
|
-
"parameters": [],
|
|
21517
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
21518
|
-
"docsTags": []
|
|
21519
|
-
}
|
|
21520
|
-
],
|
|
21287
|
+
"methods": [],
|
|
21521
21288
|
"events": [
|
|
21522
21289
|
{
|
|
21523
21290
|
"event": "mdsPrefChange",
|
|
@@ -21581,8 +21348,8 @@
|
|
|
21581
21348
|
}
|
|
21582
21349
|
],
|
|
21583
21350
|
"usage": {
|
|
21584
|
-
"1. Description": "The `<mds-pref-language>` web component is the language-preference control of the Magma Design System, designed to be slotted inside [`<mds-pref>`](../../mds-pref) alongside the other preference children. It renders a labelled tab trigger that opens a dropdown of `<mds-pref-language-item>` entries, letting users switch the active document language and persisting that choice.\n\n#### Semantic Behavior\n\n- **Compound child constraint**: Must be placed as a direct slot child of `<mds-pref>`. In turn it acts as the host for its own `<mds-pref-language-item>` children, supplied via its default slot.\n- **Default slot hosts the items**: The default slot accepts one or more `<mds-pref-language-item>` elements; the item whose `code` matches `set` is marked selected.\n- **Selection orchestration**: Selecting an item clears the others, closes the dropdown, and resolves the new language - the children report up to this component, which centralizes the single-selection state.\n- **Language resolution & persistence**: When `set` is `auto` the active language is resolved in priority order from the persisted value, then the `<html lang>` attribute, then `navigator.language`. The resolved value is persisted and
|
|
21585
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref-language>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Language Selector Inside `mds-pref`\n\nThe canonical usage. Nest `<mds-pref-language>` as a direct child of [`<mds-pref>`](../../mds-pref) and populate its default slot with one [`<mds-pref-language-item>`](../../mds-pref-language-item) per supported locale. The `code` attribute on each item must be a valid BCP 47 short tag.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Forcing a Starting Language with `set`\n\nPass an explicit BCP 47 tag to `set` to override the automatic resolution chain. Use this when the application dictates an initial language regardless of the user's browser setting or persisted preference.\n\n```html\n<mds-pref>\n <mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Automatic Language Resolution (default)\n\nOmit `set` (or pass `set=\"auto\"`) to let the component resolve the active language in priority order: persisted user choice, then the page `<html lang>` attribute, then `navigator.language`. This is the right choice for most applications.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Sizing via `size`\n\nUse the `size` prop when this control must differ from the rest of the preference group. Prefer setting `size` on the parent [`<mds-pref>`](../../mds-pref) so all preference children stay visually consistent; set it here only when this child must deviate.\n\n```html\n<!-- Preferred: size set once on the parent -->\n<mds-pref size=\"sm\">\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n\n<!-- Acceptable: size set directly on the language control when it must deviate -->\n<mds-pref>\n <mds-pref-language size=\"sm\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Listening for Language Changes\n\nListen to `mdsPrefLanguageChange` to react when the user picks a new language (for example, to reload the page or re-fetch translated content). The event detail carries the selected `language` code string.\n\n```html\n<mds-pref>\n <mds-pref-language id=\"lang-selector\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n\n<script>\n document.querySelector('#lang-selector').addEventListener('mdsPrefLanguageChange', (e) => {\n console.log('Nuova lingua selezionata:', e.detail.language);\n // e.g. reload the page to apply the new locale\n window.location.reload();\n });\n</script>\n```\n\n#### Full Preference Panel with Language\n\n`<mds-pref-language>` is one of several preference children accepted by [`<mds-pref>`](../../mds-pref). Compose it alongside the other controls to offer a complete preferences UI.\n\n```html\n<mds-pref>\n <mds-pref-
|
|
21351
|
+
"1. Description": "The `<mds-pref-language>` web component is the language-preference control of the Magma Design System, designed to be slotted inside [`<mds-pref>`](../../mds-pref) alongside the other preference children. It renders a labelled tab trigger that opens a dropdown of `<mds-pref-language-item>` entries, letting users switch the active document language and persisting that choice.\n\n#### Semantic Behavior\n\n- **Compound child constraint**: Must be placed as a direct slot child of `<mds-pref>`. In turn it acts as the host for its own `<mds-pref-language-item>` children, supplied via its default slot.\n- **Default slot hosts the items**: The default slot accepts one or more `<mds-pref-language-item>` elements; the item whose `code` matches `set` is marked selected.\n- **Selection orchestration**: Selecting an item clears the others, closes the dropdown, and resolves the new language - the children report up to this component, which centralizes the single-selection state.\n- **Language resolution & persistence**: When `set` is `auto` the active language is resolved in priority order from the persisted value, then the `<html lang>` attribute, then `navigator.language`. The resolved value is persisted and written to `<html lang>` — the single page-wide source of truth for the language. Every localized Magma component (including ones nested in shadow DOM) reacts automatically through a shared reactive store; there is no per-element `lang` override and no imperative refresh method. Applications that manage the language themselves can simply set `<html lang>`: the store observes it.\n- **Events bubbled to the parent**: Emits `mdsPrefLanguageChange` (detail carries the selected `language` code) and `mdsPrefChange` (detail `{ preference: 'language' }`), fired only when the resolved language actually changes (the initial application on load does not emit). The latter is consumed by `<mds-pref>` to show its \"reload required\" notice, since application-level content may still need a reload.\n- **Invalid codes throw**: A `set` value that is neither `auto` nor a valid `xx` / `xx-XX` BCP 47 short form raises an error rather than failing silently.\n- **Default-language hint**: When the resolved language differs from the built-in default (`en`), a caption noting the default language is rendered.\n\n#### Properties & Visual Configurations\n\n- **`set`**: The desired language as a BCP 47 short tag (e.g. `it`, `en`, `es-ES`); the special value `auto` (default) defers to the persisted/page/system resolution chain described above. Region subtags are sanitized down to the two-letter language. Set an explicit value only to force a starting language regardless of the user's environment. Supported display languages are Italiano, English, Español and ελληνικά.\n- **`size`**: Sizes the nested tab trigger (`sm` / `md`). Prefer setting `size` on the parent `<mds-pref>` so the whole preference group stays visually consistent; set it here only when this child must deviate.\n",
|
|
21352
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref-language>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Language Selector Inside `mds-pref`\n\nThe canonical usage. Nest `<mds-pref-language>` as a direct child of [`<mds-pref>`](../../mds-pref) and populate its default slot with one [`<mds-pref-language-item>`](../../mds-pref-language-item) per supported locale. The `code` attribute on each item must be a valid BCP 47 short tag.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Forcing a Starting Language with `set`\n\nPass an explicit BCP 47 tag to `set` to override the automatic resolution chain. Use this when the application dictates an initial language regardless of the user's browser setting or persisted preference.\n\n```html\n<mds-pref>\n <mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Automatic Language Resolution (default)\n\nOmit `set` (or pass `set=\"auto\"`) to let the component resolve the active language in priority order: persisted user choice, then the page `<html lang>` attribute, then `navigator.language`. This is the right choice for most applications.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Sizing via `size`\n\nUse the `size` prop when this control must differ from the rest of the preference group. Prefer setting `size` on the parent [`<mds-pref>`](../../mds-pref) so all preference children stay visually consistent; set it here only when this child must deviate.\n\n```html\n<!-- Preferred: size set once on the parent -->\n<mds-pref size=\"sm\">\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n\n<!-- Acceptable: size set directly on the language control when it must deviate -->\n<mds-pref>\n <mds-pref-language size=\"sm\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Listening for Language Changes\n\nListen to `mdsPrefLanguageChange` to react when the user picks a new language (for example, to reload the page or re-fetch translated content). The event detail carries the selected `language` code string.\n\n```html\n<mds-pref>\n <mds-pref-language id=\"lang-selector\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n\n<script>\n document.querySelector('#lang-selector').addEventListener('mdsPrefLanguageChange', (e) => {\n console.log('Nuova lingua selezionata:', e.detail.language);\n // e.g. reload the page to apply the new locale\n window.location.reload();\n });\n</script>\n```\n\n#### Full Preference Panel with Language\n\n`<mds-pref-language>` is one of several preference children accepted by [`<mds-pref>`](../../mds-pref). Compose it alongside the other controls to offer a complete preferences UI.\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n",
|
|
21586
21353
|
"3. Antipattern": "Common incorrect uses of `<mds-pref-language>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use Outside `mds-pref`\n\n`<mds-pref-language>` is a compound child designed to live inside [`<mds-pref>`](../../mds-pref). Using it as a standalone widget breaks parent-child communication and prevents the reload-required notice from appearing.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n</mds-pref-language>\n\n<!-- ✅ CORRECT -->\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Do Not Slot Arbitrary HTML Instead of `mds-pref-language-item`\n\nThe default slot accepts only `<mds-pref-language-item>` elements. Slotting raw `<button>`, `<li>`, or other elements bypasses the selection orchestration and event wiring the parent depends on.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref>\n <mds-pref-language>\n <button>Italiano</button>\n <button>English</button>\n </mds-pref-language>\n</mds-pref>\n\n<!-- ✅ CORRECT -->\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Do Not Pass an Unrecognized Language Code to `set`\n\nThe `set` prop must be either `\"auto\"` or a valid two-letter BCP 47 tag (`xx` or `xx-XX`). Any other value - including full locale strings like `\"italiano\"`, ISO 639-2 three-letter codes, or malformed strings - throws an error at runtime.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-language set=\"italiano\">...</mds-pref-language>\n<mds-pref-language set=\"en_US\">...</mds-pref-language>\n\n<!-- ✅ CORRECT -->\n<mds-pref-language set=\"it\">...</mds-pref-language>\n<mds-pref-language set=\"en\">...</mds-pref-language>\n<mds-pref-language set=\"es-ES\">...</mds-pref-language>\n```\n\n#### Do Not Set `selected` Manually on `mds-pref-language-item`\n\nThe parent `<mds-pref-language>` manages the `selected` state of each item automatically based on the active language. Setting `selected` by hand causes a mismatch between the visual selection and the internal state, and will be overwritten on the next render cycle.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref>\n <mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\" selected></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n\n<!-- ✅ CORRECT - the parent derives selection from `set` -->\n<mds-pref>\n <mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Do Not Listen to `mdsPrefLanguageItemSelect` Instead of `mdsPrefLanguageChange`\n\n`mdsPrefLanguageItemSelect` is the internal event emitted by `<mds-pref-language-item>` and consumed by its parent. Application code should listen to `mdsPrefLanguageChange` on `<mds-pref-language>`, which fires only after the selection has been committed and the language has been applied.\n\n```html\n<!-- 🚫 INCORRECT -->\n<script>\n document.querySelector('mds-pref-language-item').addEventListener('mdsPrefLanguageItemSelect', (e) => {\n console.log(e.detail.language);\n });\n</script>\n\n<!-- ✅ CORRECT -->\n<script>\n document.querySelector('mds-pref-language').addEventListener('mdsPrefLanguageChange', (e) => {\n console.log(e.detail.language);\n });\n</script>\n```\n\n#### Do Not Set Size via CSS Instead of the `size` Prop\n\nThe `size` prop is the only supported way to resize the internal tab trigger. Overriding dimensions with inline styles or CSS custom properties not listed in the component's documented surface couples your code to internal implementation details.\n\n```css\n/* 🚫 INCORRECT */\nmds-pref-language mds-tab-item {\n font-size: 10px;\n}\n```\n\n```html\n<!-- ✅ CORRECT -->\n<mds-pref size=\"sm\">\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n"
|
|
21587
21354
|
},
|
|
21588
21355
|
"props": [
|
|
@@ -21654,30 +21421,7 @@
|
|
|
21654
21421
|
"setter": false
|
|
21655
21422
|
}
|
|
21656
21423
|
],
|
|
21657
|
-
"methods": [
|
|
21658
|
-
{
|
|
21659
|
-
"name": "updateLang",
|
|
21660
|
-
"returns": {
|
|
21661
|
-
"type": "Promise<void>",
|
|
21662
|
-
"docs": ""
|
|
21663
|
-
},
|
|
21664
|
-
"complexType": {
|
|
21665
|
-
"signature": "() => Promise<void>",
|
|
21666
|
-
"parameters": [],
|
|
21667
|
-
"references": {
|
|
21668
|
-
"Promise": {
|
|
21669
|
-
"location": "global",
|
|
21670
|
-
"id": "global::Promise"
|
|
21671
|
-
}
|
|
21672
|
-
},
|
|
21673
|
-
"return": "Promise<void>"
|
|
21674
|
-
},
|
|
21675
|
-
"signature": "updateLang() => Promise<void>",
|
|
21676
|
-
"parameters": [],
|
|
21677
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
21678
|
-
"docsTags": []
|
|
21679
|
-
}
|
|
21680
|
-
],
|
|
21424
|
+
"methods": [],
|
|
21681
21425
|
"events": [
|
|
21682
21426
|
{
|
|
21683
21427
|
"event": "mdsPrefChange",
|
|
@@ -21765,7 +21509,7 @@
|
|
|
21765
21509
|
"docsTags": [],
|
|
21766
21510
|
"usage": {
|
|
21767
21511
|
"1. Description": "The `<mds-pref-language-item>` web component represents a single selectable language option inside the language-preference picker [`<mds-pref-language>`](../../mds-pref-language). It renders one row of the parent's dropdown and reports the user's choice up to the parent rather than changing the page language itself.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-pref-language>`; it is not used standalone or mixed with other child types.\n- **Code validation**: `code` must match an entry in the bundled language dictionary; an unknown `code` throws `Language code not found: <code>`. When `code` is empty the item renders an error-toned fallback button instead of a language label.\n- **Label is derived, not authored**: The visible language name is looked up from `code` (e.g. `it` to `Italiano`), so consumers supply only the code, not the display text.\n- **Selection is parent-driven**: The `selected` prop is owned and toggled by `<mds-pref-language>`, which clears every sibling and sets only the active item.\n- **Click emits, does not commit**: Clicking the item emits the bubbling `mdsPrefLanguageItemSelect` event carrying `{ language: code }`. The parent updates selection state, persists the preference, applies the document language, and emits its own `mdsPrefLanguageChange` - this child performs none of that.\n\n#### Properties & Visual Configurations\n\nThe only meaningful prop is `code`: the BCP 47 / RFC 5646 language tag (such as `it`, `en`, `es`) that both keys the label lookup and is the payload emitted on selection. The set of accepted codes is defined by the bundled dictionary in `meta/locale.json`.\n\n`selected` is a state flag managed by the parent rather than a configuration choice. Sizing and styling are fixed by the parent's layout, so this item exposes no `variant` / `tone` of its own; the shared ladders in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system) are applied internally and are not configurable from the host.\n",
|
|
21768
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref-language-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of compound-component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Language List Inside the Parent\n\nThe canonical form. Place one `<mds-pref-language-item>` per supported language as a direct child of [`<mds-pref-language>`](../../mds-pref-language). Set `code` to a BCP 47 tag that exists in the bundled dictionary; the component resolves the display name automatically.\n\n```html\n<mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"fr\"></mds-pref-language-item>\n</mds-pref-language>\n```\n\n#### Pre-selecting the Active Language\n\nThe `selected` prop is normally managed by the parent, but you can set it declaratively when you know the initial active language at render time. The parent will take over selection management after the first user interaction.\n\n```html\n<mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\" selected></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"de\"></mds-pref-language-item>\n</mds-pref-language>\n```\n\n#### Listening for a Language Selection\n\nThe item emits `mdsPrefLanguageItemSelect` with `{ language: code }` when clicked. In most cases you should listen on the parent (`mdsPrefLanguageChange`) rather than on individual items - but listening on the item directly is valid when you need fine-grained control.\n\n```html\n<mds-pref-language>\n <mds-pref-language-item code=\"it\" id=\"lang-it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\" id=\"lang-en\"></mds-pref-language-item>\n</mds-pref-language>\n\n<script>\n document.querySelectorAll('mds-pref-language-item').forEach((item) => {\n item.addEventListener('mdsPrefLanguageItemSelect', (e) => {\n console.log('Lingua scelta:', e.detail.language);\n });\n });\n</script>\n```\n\n#### Offering a Large Language Set\n\nAdd as many items as needed - the parent wraps them in a scrollable dropdown. Each item only needs a `code`; the visible label is derived automatically.\n\n```html\n<mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n <mds-pref-language-item code=\"fr\"></mds-pref-language-item>\n <mds-pref-language-item code=\"de\"></mds-pref-language-item>\n <mds-pref-language-item code=\"pt\"></mds-pref-language-item>\n <mds-pref-language-item code=\"zh\"></mds-pref-language-item>\n <mds-pref-language-item code=\"ar\"></mds-pref-language-item>\n</mds-pref-language>\n```\n\n#### Inside a Full Preferences Panel\n\n`<mds-pref-language>` and its items compose inside [`<mds-pref>`](../../mds-pref) alongside the other preference controls. Place them as direct children of `<mds-pref>`.\n\n```html\n<mds-pref>\n <mds-pref-
|
|
21512
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref-language-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of compound-component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Language List Inside the Parent\n\nThe canonical form. Place one `<mds-pref-language-item>` per supported language as a direct child of [`<mds-pref-language>`](../../mds-pref-language). Set `code` to a BCP 47 tag that exists in the bundled dictionary; the component resolves the display name automatically.\n\n```html\n<mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"fr\"></mds-pref-language-item>\n</mds-pref-language>\n```\n\n#### Pre-selecting the Active Language\n\nThe `selected` prop is normally managed by the parent, but you can set it declaratively when you know the initial active language at render time. The parent will take over selection management after the first user interaction.\n\n```html\n<mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\" selected></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"de\"></mds-pref-language-item>\n</mds-pref-language>\n```\n\n#### Listening for a Language Selection\n\nThe item emits `mdsPrefLanguageItemSelect` with `{ language: code }` when clicked. In most cases you should listen on the parent (`mdsPrefLanguageChange`) rather than on individual items - but listening on the item directly is valid when you need fine-grained control.\n\n```html\n<mds-pref-language>\n <mds-pref-language-item code=\"it\" id=\"lang-it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\" id=\"lang-en\"></mds-pref-language-item>\n</mds-pref-language>\n\n<script>\n document.querySelectorAll('mds-pref-language-item').forEach((item) => {\n item.addEventListener('mdsPrefLanguageItemSelect', (e) => {\n console.log('Lingua scelta:', e.detail.language);\n });\n });\n</script>\n```\n\n#### Offering a Large Language Set\n\nAdd as many items as needed - the parent wraps them in a scrollable dropdown. Each item only needs a `code`; the visible label is derived automatically.\n\n```html\n<mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n <mds-pref-language-item code=\"fr\"></mds-pref-language-item>\n <mds-pref-language-item code=\"de\"></mds-pref-language-item>\n <mds-pref-language-item code=\"pt\"></mds-pref-language-item>\n <mds-pref-language-item code=\"zh\"></mds-pref-language-item>\n <mds-pref-language-item code=\"ar\"></mds-pref-language-item>\n</mds-pref-language>\n```\n\n#### Inside a Full Preferences Panel\n\n`<mds-pref-language>` and its items compose inside [`<mds-pref>`](../../mds-pref) alongside the other preference controls. Place them as direct children of `<mds-pref>`.\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n",
|
|
21769
21513
|
"3. Antipattern": "Common incorrect uses of `<mds-pref-language-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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use the Item Outside Its Parent\n\n`<mds-pref-language-item>` is a compound child and relies on `<mds-pref-language>` for selection management, dropdown layout, and language persistence. Using it standalone leaves the click handler dangling and the selection state unmanaged.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-language-item code=\"it\"></mds-pref-language-item>\n\n<!-- ✅ CORRECT -->\n<mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n</mds-pref-language>\n```\n\n#### Do Not Set the Display Label Manually\n\nThe item derives its label from the `code` prop via the bundled dictionary. Attempting to pass display text in the default slot or as an attribute is not supported and will be ignored by the render function.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-language-item code=\"it\">Italiano</mds-pref-language-item>\n\n<!-- ✅ CORRECT -->\n<mds-pref-language-item code=\"it\"></mds-pref-language-item>\n```\n\n#### Do Not Use an Undocumented or Misspelled Language Code\n\n`code` must exactly match a key in the bundled dictionary (e.g. `\"it\"`, `\"en\"`, `\"fr\"`). An unknown code throws `Language code not found: <code>` at render time. Use the two-letter BCP 47 tag, not a locale variant like `\"it-IT\"`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-language-item code=\"it-IT\"></mds-pref-language-item>\n<mds-pref-language-item code=\"italian\"></mds-pref-language-item>\n\n<!-- ✅ CORRECT -->\n<mds-pref-language-item code=\"it\"></mds-pref-language-item>\n```\n\n#### Do Not Manage the `selected` Prop by Hand Across Items\n\nThe parent clears every sibling and marks only the active item. If you toggle `selected` yourself on multiple items, the visual state will desync from the stored preference after the first user interaction.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-language>\n <mds-pref-language-item code=\"it\" selected></mds-pref-language-item>\n <mds-pref-language-item code=\"en\" selected></mds-pref-language-item>\n</mds-pref-language>\n\n<!-- ✅ CORRECT -->\n<mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n</mds-pref-language>\n```\n\n#### Do Not Listen for Native `click` to Detect Language Selection\n\nThe component emits `mdsPrefLanguageItemSelect` (or the parent emits `mdsPrefLanguageChange`). Native `click` may not propagate reliably out of shadow DOM and skips the event payload that carries the selected language code.\n\n```html\n<!-- 🚫 INCORRECT -->\n<script>\n document.querySelector('mds-pref-language-item').addEventListener('click', () => {\n // no language code available here\n });\n</script>\n\n<!-- ✅ CORRECT -->\n<script>\n document.querySelector('mds-pref-language').addEventListener('mdsPrefLanguageChange', (e) => {\n console.log('Lingua selezionata:', e.detail.language);\n });\n</script>\n```\n\n#### Do Not Set `selected=\"false\"` to Deselect\n\n`selected` is a boolean attribute. The string `\"false\"` is truthy in HTML and will keep the item visually selected. Remove the attribute or set the prop to `undefined` to deselect programmatically.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-language-item code=\"it\" selected=\"false\"></mds-pref-language-item>\n\n<!-- ✅ CORRECT -->\n<mds-pref-language-item code=\"it\"></mds-pref-language-item>\n```\n"
|
|
21770
21514
|
},
|
|
21771
21515
|
"props": [
|
|
@@ -21825,30 +21569,7 @@
|
|
|
21825
21569
|
"setter": false
|
|
21826
21570
|
}
|
|
21827
21571
|
],
|
|
21828
|
-
"methods": [
|
|
21829
|
-
{
|
|
21830
|
-
"name": "updateLang",
|
|
21831
|
-
"returns": {
|
|
21832
|
-
"type": "Promise<void>",
|
|
21833
|
-
"docs": ""
|
|
21834
|
-
},
|
|
21835
|
-
"complexType": {
|
|
21836
|
-
"signature": "() => Promise<void>",
|
|
21837
|
-
"parameters": [],
|
|
21838
|
-
"references": {
|
|
21839
|
-
"Promise": {
|
|
21840
|
-
"location": "global",
|
|
21841
|
-
"id": "global::Promise"
|
|
21842
|
-
}
|
|
21843
|
-
},
|
|
21844
|
-
"return": "Promise<void>"
|
|
21845
|
-
},
|
|
21846
|
-
"signature": "updateLang() => Promise<void>",
|
|
21847
|
-
"parameters": [],
|
|
21848
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
21849
|
-
"docsTags": []
|
|
21850
|
-
}
|
|
21851
|
-
],
|
|
21572
|
+
"methods": [],
|
|
21852
21573
|
"events": [
|
|
21853
21574
|
{
|
|
21854
21575
|
"event": "mdsPrefLanguageItemSelect",
|
|
@@ -21893,30 +21614,72 @@
|
|
|
21893
21614
|
}
|
|
21894
21615
|
},
|
|
21895
21616
|
{
|
|
21896
|
-
"filePath": "src/components/mds-pref-
|
|
21617
|
+
"filePath": "src/components/mds-pref-mode/mds-pref-mode.tsx",
|
|
21897
21618
|
"encapsulation": "shadow",
|
|
21898
|
-
"tag": "mds-pref-
|
|
21899
|
-
"readme": "# mds-pref-
|
|
21619
|
+
"tag": "mds-pref-mode",
|
|
21620
|
+
"readme": "# mds-pref-mode\n\n\n",
|
|
21900
21621
|
"docs": "",
|
|
21901
21622
|
"docsTags": [],
|
|
21902
21623
|
"usage": {
|
|
21903
|
-
"1. Description": "The `<mds-pref-
|
|
21904
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref-
|
|
21905
|
-
"3. Antipattern": "Common incorrect uses of `<mds-pref-
|
|
21624
|
+
"1. Description": "The `<mds-pref-mode>` web component is the mode preference control of the Magma Design System, designed to live as a direct child of [`<mds-pref>`](../../mds-pref). It renders a labelled three-way tab (light / system / dark) that lets the user pick a color-scheme mode and applies it globally to the document.\n\n#### Semantic Behavior\n\n- **Compound child only**: It is meant to be placed directly in the default slot of `<mds-pref>` alongside the other `mds-pref-*` preference children; it is not used standalone or mixed with unrelated child types.\n- **Selection follows `mode`**: The active tab reflects whichever mode is currently applied, driven by the `mode` prop.\n- **Global mode application**: Selecting a mode applies it document-wide and persists the choice.\n- **Persistence on load**: The applied mode resolves from `mode` → the stored value → the `system` default, so a previously chosen mode is restored without an explicit prop.\n- **`mdsPrefChange` event**: Emits `mdsPrefChange` with `{ preference: 'mode' }` whenever the mode is set; this bubbles up to `<mds-pref>`, which coordinates reload prompts across preference children.\n- **Safari fallback**: On Safari the control disables itself and forces `mode` to `light`, since the transition overlay technique is unsupported there.\n- **System mode**: The `system` choice follows the OS `prefers-color-scheme` media query to resolve the effective light/dark scheme.\n\n#### Properties & Visual Configurations\n\n- **`mode`**: Sets and reflects the active mode (`light`, `dark`, `system`). Leave it unset to inherit the persisted/default mode; set it explicitly to force a starting mode.\n- **`transition`**: Controls the visual switch between schemes. Use `smooth` (default) for a fading neutral overlay that flips the mode mid-fade, `flash` for an instant switch with a brief overlay pulse, or `none` to apply the new mode with no overlay animation. The overlay timing and z-index are tunable through `--mds-pref-mode-overlay-*` CSS custom properties.\n- **`size`**: Sizes the nested tab items (`sm` / `md`); normally inherited from the parent `<mds-pref>` rather than set directly, so all sibling preferences stay visually consistent.\n",
|
|
21625
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref-mode>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared preference system documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Default Usage Inside `mds-pref`\n\nThe canonical form. Slot `<mds-pref-mode>` as a direct child of [`<mds-pref>`](../../mds-pref) with no extra props. The component restores the user's previously persisted mode automatically on load.\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Setting an Initial Mode\n\nPass `mode` to force the selector to start on a specific mode rather than reading from `localStorage`. Useful when the host application controls preference state centrally.\n\n```html\n<mds-pref>\n <mds-pref-mode mode=\"dark\"></mds-pref-mode>\n</mds-pref>\n```\n\n#### Using `system` Mode for OS-Aware Default\n\n`mode=\"system\"` resolves to light or dark based on the OS `prefers-color-scheme` media query. Use this as the explicit starting point when you want the app to follow the OS without the user having to choose.\n\n```html\n<mds-pref>\n <mds-pref-mode mode=\"system\"></mds-pref-mode>\n</mds-pref>\n```\n\n#### Choosing a Transition Style\n\n`transition` controls the visual effect when switching between schemes. Use `smooth` (default) for a mid-fade overlay that hides the color flip, `flash` for an instant switch with a brief full-screen pulse, or `none` for a hard switch with no animation.\n\n```html\n<!-- Smooth fade (default) -->\n<mds-pref-mode transition=\"smooth\"></mds-pref-mode>\n\n<!-- Instant flash pulse -->\n<mds-pref-mode transition=\"flash\"></mds-pref-mode>\n\n<!-- No animation -->\n<mds-pref-mode transition=\"none\"></mds-pref-mode>\n```\n\n#### Listening for Mode Changes\n\nThe component emits `mdsPrefChange` with `{ preference: 'mode' }` each time the mode is applied. Listen for this event to react in application code - for example to sync a preference state store.\n\n```html\n<mds-pref>\n <mds-pref-mode id=\"mode-selector\"></mds-pref-mode>\n</mds-pref>\n\n<script>\n document.getElementById('mode-selector').addEventListener('mdsPrefChange', (e) => {\n console.log('Modalita tema cambiata:', e.detail.preference);\n });\n</script>\n```\n\n#### Controlling Size via the Parent\n\n`size` is forwarded to the internal tab items. Set it once on [`<mds-pref>`](../../mds-pref) to keep all sibling preference controls at the same tab size. Setting it directly on `<mds-pref-mode>` is valid only when the component is used outside the standard panel - for instance in a compact header toolbar.\n\n```html\n<!-- Preferred: size set on the parent cascades down automatically -->\n<mds-pref size=\"sm\">\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n\n<!-- Only set size directly when used standalone -->\n<mds-pref-mode size=\"sm\"></mds-pref-mode>\n```\n\n#### Customizing the Transition Overlay\n\nTune the overlay timing and stacking order via the documented `--mds-pref-mode-overlay-*` CSS custom properties. Set them on the host or a parent selector. Use Magma time tokens where available so animations stay in sync with the design system.\n\n```css\nmds-pref-mode {\n --mds-pref-mode-overlay-show-duration: 400ms;\n --mds-pref-mode-overlay-fadeout-duration: 250ms;\n --mds-pref-mode-overlay-z-index: 9000;\n}\n```\n",
|
|
21626
|
+
"3. Antipattern": "Common incorrect uses of `<mds-pref-mode>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-pref-mode>` Outside `<mds-pref>`\n\n`<mds-pref-mode>` is a compound child; it communicates with the parent via the `mdsPrefChange` event and relies on `<mds-pref>` to propagate `size` and coordinate reload prompts. Using it as a standalone widget breaks those contracts.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-mode></mds-pref-mode>\n\n<!-- ✅ CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Set `transition=\"false\"` to Disable the Overlay\n\n`transition` is a string enum, not a boolean. Setting it to `\"false\"` is not a valid value and will silently fall back to the default `smooth` behavior. Use `transition=\"none\"` to opt out of the overlay animation.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-mode transition=\"false\"></mds-pref-mode>\n\n<!-- ✅ CORRECT -->\n<mds-pref-mode transition=\"none\"></mds-pref-mode>\n```\n\n#### Do Not Listen for Native `change` Events Instead of `mdsPrefChange`\n\nThe component does not emit or bubble native `change` events out of the shadow DOM. Always listen for the documented `mdsPrefChange` custom event.\n\n```html\n<!-- 🚫 INCORRECT -->\n<script>\n document.querySelector('mds-pref-mode').addEventListener('change', handler);\n</script>\n\n<!-- ✅ CORRECT -->\n<script>\n document.querySelector('mds-pref-mode').addEventListener('mdsPrefChange', handler);\n</script>\n```\n\n#### Do Not Override Mode Classes on `<html>` Directly\n\nThe component manages `pref-mode-light`, `pref-mode-dark`, and `pref-mode-system` classes on `<html>` itself. Adding or removing these by hand races with the component and will be overwritten on the next mode change. Drive the mode exclusively through the `mode` prop.\n\n```html\n<!-- 🚫 INCORRECT -->\n<script>\n document.documentElement.classList.add('pref-mode-dark');\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-pref>\n <mds-pref-mode mode=\"dark\"></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Set `size` on Every Child Separately\n\n`size` is designed to cascade from `<mds-pref>` to all its preference children at once. Setting it individually on `<mds-pref-mode>` when siblings exist produces inconsistent tab sizes across the panel.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref>\n <mds-pref-mode size=\"sm\"></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n</mds-pref>\n\n<!-- ✅ CORRECT -->\n<mds-pref size=\"sm\">\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n</mds-pref>\n```\n\n#### Do Not Pierce the Shadow DOM to Customize Overlay Appearance\n\nThe overlay element is injected into `document.body` at runtime with inline styles. Do not target it by class name or adjust its properties through JavaScript. Use the documented `--mds-pref-mode-overlay-*` CSS custom properties instead.\n\n```css\n/* 🚫 INCORRECT */\n.mds-pref-mode-overlay {\n background-color: black;\n z-index: 99999;\n}\n\n/* ✅ CORRECT */\nmds-pref-mode {\n --mds-pref-mode-overlay-show-duration: 400ms;\n --mds-pref-mode-overlay-z-index: 9000;\n}\n```\n"
|
|
21906
21627
|
},
|
|
21907
21628
|
"props": [
|
|
21629
|
+
{
|
|
21630
|
+
"name": "lockedScheme",
|
|
21631
|
+
"type": "\"all\" | \"dark\" | \"light\" | undefined",
|
|
21632
|
+
"complexType": {
|
|
21633
|
+
"original": "PreferenceThemeSchemeType",
|
|
21634
|
+
"resolved": "\"all\" | \"dark\" | \"light\" | undefined",
|
|
21635
|
+
"references": {
|
|
21636
|
+
"PreferenceThemeSchemeType": {
|
|
21637
|
+
"location": "import",
|
|
21638
|
+
"path": "@type/preference",
|
|
21639
|
+
"id": "src/type/preference.ts::PreferenceThemeSchemeType",
|
|
21640
|
+
"referenceLocation": "PreferenceThemeSchemeType"
|
|
21641
|
+
}
|
|
21642
|
+
}
|
|
21643
|
+
},
|
|
21644
|
+
"mutable": false,
|
|
21645
|
+
"attr": "locked-scheme",
|
|
21646
|
+
"reflectToAttr": true,
|
|
21647
|
+
"docs": "Locks the mode items forbidden by a scheme-constrained theme, without\ntouching the stored preference: `light` disables the explicit `dark` item,\n`dark` disables the explicit `light` item, `all` (or unset) locks nothing;\nthe `system` item is never locked. Set by the `mds-pref` controller from the\nactive theme's `scheme`; not meant to be set directly.",
|
|
21648
|
+
"docsTags": [],
|
|
21649
|
+
"values": [
|
|
21650
|
+
{
|
|
21651
|
+
"value": "all",
|
|
21652
|
+
"type": "string"
|
|
21653
|
+
},
|
|
21654
|
+
{
|
|
21655
|
+
"value": "dark",
|
|
21656
|
+
"type": "string"
|
|
21657
|
+
},
|
|
21658
|
+
{
|
|
21659
|
+
"value": "light",
|
|
21660
|
+
"type": "string"
|
|
21661
|
+
},
|
|
21662
|
+
{
|
|
21663
|
+
"type": "undefined"
|
|
21664
|
+
}
|
|
21665
|
+
],
|
|
21666
|
+
"optional": true,
|
|
21667
|
+
"required": false,
|
|
21668
|
+
"getter": false,
|
|
21669
|
+
"setter": false
|
|
21670
|
+
},
|
|
21908
21671
|
{
|
|
21909
21672
|
"name": "mode",
|
|
21910
21673
|
"type": "\"dark\" | \"light\" | \"system\" | undefined",
|
|
21911
21674
|
"complexType": {
|
|
21912
|
-
"original": "
|
|
21675
|
+
"original": "PreferenceModeType",
|
|
21913
21676
|
"resolved": "\"dark\" | \"light\" | \"system\" | undefined",
|
|
21914
21677
|
"references": {
|
|
21915
|
-
"
|
|
21678
|
+
"PreferenceModeType": {
|
|
21916
21679
|
"location": "import",
|
|
21917
21680
|
"path": "@type/preference",
|
|
21918
|
-
"id": "src/type/preference.ts::
|
|
21919
|
-
"referenceLocation": "
|
|
21681
|
+
"id": "src/type/preference.ts::PreferenceModeType",
|
|
21682
|
+
"referenceLocation": "PreferenceModeType"
|
|
21920
21683
|
}
|
|
21921
21684
|
}
|
|
21922
21685
|
},
|
|
@@ -22003,7 +21766,7 @@
|
|
|
22003
21766
|
"mutable": true,
|
|
22004
21767
|
"attr": "transition",
|
|
22005
21768
|
"reflectToAttr": true,
|
|
22006
|
-
"docs": "Specifies the transition of switching from a
|
|
21769
|
+
"docs": "Specifies the transition of switching from a mode to another one",
|
|
22007
21770
|
"docsTags": [
|
|
22008
21771
|
{
|
|
22009
21772
|
"name": "default",
|
|
@@ -22031,30 +21794,7 @@
|
|
|
22031
21794
|
"setter": false
|
|
22032
21795
|
}
|
|
22033
21796
|
],
|
|
22034
|
-
"methods": [
|
|
22035
|
-
{
|
|
22036
|
-
"name": "updateLang",
|
|
22037
|
-
"returns": {
|
|
22038
|
-
"type": "Promise<void>",
|
|
22039
|
-
"docs": ""
|
|
22040
|
-
},
|
|
22041
|
-
"complexType": {
|
|
22042
|
-
"signature": "() => Promise<void>",
|
|
22043
|
-
"parameters": [],
|
|
22044
|
-
"references": {
|
|
22045
|
-
"Promise": {
|
|
22046
|
-
"location": "global",
|
|
22047
|
-
"id": "global::Promise"
|
|
22048
|
-
}
|
|
22049
|
-
},
|
|
22050
|
-
"return": "Promise<void>"
|
|
22051
|
-
},
|
|
22052
|
-
"signature": "updateLang() => Promise<void>",
|
|
22053
|
-
"parameters": [],
|
|
22054
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
22055
|
-
"docsTags": []
|
|
22056
|
-
}
|
|
22057
|
-
],
|
|
21797
|
+
"methods": [],
|
|
22058
21798
|
"events": [
|
|
22059
21799
|
{
|
|
22060
21800
|
"event": "mdsPrefChange",
|
|
@@ -22090,7 +21830,7 @@
|
|
|
22090
21830
|
"mds-tab-item"
|
|
22091
21831
|
],
|
|
22092
21832
|
"dependencyGraph": {
|
|
22093
|
-
"mds-pref-
|
|
21833
|
+
"mds-pref-mode": [
|
|
22094
21834
|
"mds-text",
|
|
22095
21835
|
"mds-tab",
|
|
22096
21836
|
"mds-tab-item"
|
|
@@ -22106,23 +21846,81 @@
|
|
|
22106
21846
|
}
|
|
22107
21847
|
},
|
|
22108
21848
|
{
|
|
22109
|
-
"filePath": "src/components/mds-pref-theme
|
|
21849
|
+
"filePath": "src/components/mds-pref-theme/mds-pref-theme.tsx",
|
|
22110
21850
|
"encapsulation": "shadow",
|
|
22111
|
-
"tag": "mds-pref-theme
|
|
22112
|
-
"readme": "# mds-pref-theme
|
|
21851
|
+
"tag": "mds-pref-theme",
|
|
21852
|
+
"readme": "# mds-pref-theme\n\n\n",
|
|
22113
21853
|
"docs": "",
|
|
22114
21854
|
"docsTags": [
|
|
22115
21855
|
{
|
|
22116
21856
|
"name": "slot",
|
|
22117
|
-
"text": "- Add `mds-pref-theme-
|
|
21857
|
+
"text": "- Add `mds-pref-theme-item` element/s."
|
|
22118
21858
|
}
|
|
22119
21859
|
],
|
|
22120
21860
|
"usage": {
|
|
22121
|
-
"1. Description": "The `<mds-pref-theme
|
|
22122
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref-theme
|
|
22123
|
-
"3. Antipattern": "Common incorrect uses of `<mds-pref-theme
|
|
21861
|
+
"1. Description": "The `<mds-pref-theme>` web component is the theme-switcher segment of the Magma accessibility preferences panel, designed to live as a direct child of [`<mds-pref>`](../../mds-pref). It renders a labelled tab trigger that opens a dropdown of selectable theme variants and, when a variant is chosen, applies it globally to the document.\n\n#### Semantic Behavior\n\n- **Compound positioning**: It must be a direct slot child of `<mds-pref>` and is not used standalone.\n- **Acts as a sub-parent itself**: Its own default slot must contain one or more `mds-pref-theme-item` elements; it drives their selected state so only the active theme is marked selected.\n- **Global theme application**: Selecting an item applies the theme document-wide.\n- **Persistence and hydration**: The current name and scheme are persisted and restored across reloads regardless of the declared `name` default.\n- **Name validation**: An invalid theme name (not lowercase kebab-case matching `^[a-z]+(-[a-z]+)*$`) throws at runtime when the theme is applied. So do the reserved names `light`, `dark` and `system` (they are mode values) and `scheme` or `scheme-*` (they would collide with the `pref-theme-scheme-*` classes).\n- **Events bubbled up**: Emits `mdsPrefThemeChange` with the `{ name, scheme }` detail on selection, and `mdsPrefChange` (`preference: 'theme'`) which `<mds-pref>` listens to.\n- **Localized label**: The \"Theme\" heading follows the active interface language.\n\n#### Properties & Visual Configurations\n\n- **`name`**: The active theme name (default `'default'`); it is overridden at runtime by any persisted value. Use it to declare the initial theme when no preference has been stored yet.\n- **`scheme`**: Constrains the colour modes of the theme to `'light'`, `'dark'`, or `'all'` (default). Pick `'all'` for themes that ship both light and dark palettes; pick `'light'` or `'dark'` to force a single mode for a variant that only defines one.\n- **`size`**: Sets the size (`'sm'` / `'md'`) of the nested tab UI. It is normally not set directly - `<mds-pref>` propagates its own `size` down to every `mds-pref-*` segment so the panel stays visually consistent.\n",
|
|
21862
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref-theme>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the preferences system documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Theme Chooser\n\nThe canonical form. Place `<mds-pref-theme>` inside [`<mds-pref>`](../../mds-pref) and populate its default slot with one [`<mds-pref-theme-item>`](../../mds-pref-theme-item) per available theme. The first item's `name` must match the `name` prop on the parent so the correct item starts as selected.\n\n```html\n<mds-pref>\n <mds-pref-theme name=\"default\" scheme=\"all\">\n <mds-pref-theme-item label=\"Predefinito\" name=\"default\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Estate\" name=\"summer\" scheme=\"light\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Crepuscolo\" name=\"twilight\" scheme=\"dark\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Scheme-Constrained Themes\n\nUse `scheme=\"light\"` or `scheme=\"dark\"` on a `<mds-pref-theme-item>` when the theme only defines one colour mode. The parent component propagates the chosen scheme to `<html>` and forces that mode even if the user's OS prefers the opposite.\n\n```html\n<mds-pref>\n <mds-pref-theme name=\"default\" scheme=\"all\">\n <mds-pref-theme-item label=\"Predefinito\" name=\"default\" scheme=\"all\"></mds-pref-theme-item>\n <!-- light-only palette - dark mode will not activate for this theme -->\n <mds-pref-theme-item label=\"Chiaro\" name=\"corporate\" scheme=\"light\"></mds-pref-theme-item>\n <!-- dark-only palette -->\n <mds-pref-theme-item label=\"Notte\" name=\"midnight\" scheme=\"dark\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Listening for the Change Event\n\nReact to the user's selection via `mdsPrefThemeChange`. The event detail carries `{ name, scheme }` - use them to update any app-level state that tracks the active theme.\n\n```html\n<mds-pref>\n <mds-pref-theme id=\"theme-chooser\" name=\"default\" scheme=\"all\">\n <mds-pref-theme-item label=\"Predefinito\" name=\"default\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Estate\" name=\"summer\" scheme=\"light\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n\n<script>\n document.querySelector('#theme-chooser').addEventListener('mdsPrefThemeChange', (e) => {\n console.log('Tema attivo:', e.detail.name, '- Schema:', e.detail.scheme);\n });\n</script>\n```\n\n#### Declaring the Initial Theme\n\nUse the `name` prop to declare which theme should be active before the user makes a selection. If `localStorage` already holds a persisted value it takes precedence; otherwise the component applies `name` on first render.\n\n```html\n<mds-pref>\n <!-- First-visit default is \"estate\" -->\n <mds-pref-theme name=\"summer\" scheme=\"light\">\n <mds-pref-theme-item label=\"Predefinito\" name=\"default\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Estate\" name=\"summer\" scheme=\"light\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Controlling Item Size\n\nPass `size=\"sm\"` when the preferences panel must fit a compact layout. Normally `<mds-pref>` propagates its own `size` to every `mds-pref-*` child automatically; set it directly only when using `<mds-pref-theme>` without its parent.\n\n```html\n<mds-pref size=\"sm\">\n <mds-pref-theme name=\"default\" scheme=\"all\" size=\"sm\">\n <mds-pref-theme-item label=\"Predefinito\" name=\"default\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Estate\" name=\"summer\" scheme=\"light\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Styling Theme Items\n\nStyle theme items only through their documented `--mds-pref-theme-item-*` CSS custom properties. Set them on the item host or on a parent selector; use Magma colour tokens via `rgb(var(--<token>))` to stay compatible with dark mode.\n\n```css\nmds-pref-theme-item {\n --mds-pref-theme-item-color-background: rgb(var(--tone-neutral-01));\n --mds-pref-theme-item-color-variant-primary: rgb(var(--variant-primary-05));\n}\n```\n",
|
|
21863
|
+
"3. Antipattern": "Common incorrect uses of `<mds-pref-theme>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind colour utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use the Component Outside `<mds-pref>`\n\n`<mds-pref-theme>` is a compound sub-part designed to slot inside [`<mds-pref>`](../../mds-pref). Using it standalone breaks the shared preferences panel layout and removes the size propagation cascade from the parent.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-theme name=\"default\" scheme=\"all\">\n <mds-pref-theme-item label=\"Predefinito\" name=\"default\" scheme=\"all\"></mds-pref-theme-item>\n</mds-pref-theme>\n\n<!-- ✅ CORRECT -->\n<mds-pref>\n <mds-pref-theme name=\"default\" scheme=\"all\">\n <mds-pref-theme-item label=\"Predefinito\" name=\"default\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Do Not Put Plain Text or Arbitrary HTML in the Default Slot\n\nThe default slot is reserved exclusively for `<mds-pref-theme-item>` elements. Any other content bypasses the component's internal selection management and will not trigger theme application.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref>\n <mds-pref-theme name=\"default\" scheme=\"all\">\n <button>Predefinito</button>\n <span>Estate</span>\n </mds-pref-theme>\n</mds-pref>\n\n<!-- ✅ CORRECT -->\n<mds-pref>\n <mds-pref-theme name=\"default\" scheme=\"all\">\n <mds-pref-theme-item label=\"Predefinito\" name=\"default\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Estate\" name=\"summer\" scheme=\"light\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Do Not Use an Invalid Theme Name\n\nThe `name` prop must match the pattern `^[a-z]+(-[a-z]+)*$` (lowercase letters and hyphens only). Any other value - including uppercase, underscores, or spaces - throws a runtime error when the component tries to apply the theme class on `<html>`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-theme name=\"My Theme\" scheme=\"all\">...</mds-pref-theme>\n<mds-pref-theme name=\"my_theme\" scheme=\"all\">...</mds-pref-theme>\n<mds-pref-theme name=\"MyTheme\" scheme=\"all\">...</mds-pref-theme>\n\n<!-- ✅ CORRECT -->\n<mds-pref-theme name=\"my-theme\" scheme=\"all\">...</mds-pref-theme>\n```\n\n#### Do Not Listen for the Native `change` Event\n\n`<mds-pref-theme>` emits `mdsPrefThemeChange` - a documented custom event with a typed `{ name, scheme }` detail. Listening for the native `change` event will not fire because theme selection is handled entirely inside shadow DOM.\n\n```html\n<!-- 🚫 INCORRECT -->\n<script>\n document.querySelector('mds-pref-theme').addEventListener('change', (e) => {\n console.log(e.target.value); // undefined - wrong event, wrong detail shape\n });\n</script>\n\n<!-- ✅ CORRECT -->\n<script>\n document.querySelector('mds-pref-theme').addEventListener('mdsPrefThemeChange', (e) => {\n console.log(e.detail.name, e.detail.scheme);\n });\n</script>\n```\n\n#### Do Not Set `size` Independently When Inside `<mds-pref>`\n\n`<mds-pref>` propagates its own `size` value to all `mds-pref-*` children automatically. Setting `size` directly on `<mds-pref-theme>` while it is inside `<mds-pref>` creates a conflict and the panel may render inconsistently.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref size=\"sm\">\n <mds-pref-theme size=\"md\" name=\"default\" scheme=\"all\">\n <mds-pref-theme-item label=\"Predefinito\" name=\"default\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n\n<!-- ✅ CORRECT -->\n<mds-pref size=\"sm\">\n <mds-pref-theme name=\"default\" scheme=\"all\">\n <mds-pref-theme-item label=\"Predefinito\" name=\"default\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n"
|
|
22124
21864
|
},
|
|
22125
21865
|
"props": [
|
|
21866
|
+
{
|
|
21867
|
+
"name": "cornerShape",
|
|
21868
|
+
"type": "\"bevel\" | \"default\" | \"notch\" | \"round\" | \"scoop\" | \"square\" | \"squircle\" | undefined",
|
|
21869
|
+
"complexType": {
|
|
21870
|
+
"original": "PreferenceCornerShapeChoiceType",
|
|
21871
|
+
"resolved": "\"bevel\" | \"default\" | \"notch\" | \"round\" | \"scoop\" | \"square\" | \"squircle\" | undefined",
|
|
21872
|
+
"references": {
|
|
21873
|
+
"PreferenceCornerShapeChoiceType": {
|
|
21874
|
+
"location": "import",
|
|
21875
|
+
"path": "@type/preference",
|
|
21876
|
+
"id": "src/type/preference.ts::PreferenceCornerShapeChoiceType",
|
|
21877
|
+
"referenceLocation": "PreferenceCornerShapeChoiceType"
|
|
21878
|
+
}
|
|
21879
|
+
}
|
|
21880
|
+
},
|
|
21881
|
+
"mutable": true,
|
|
21882
|
+
"attr": "corner-shape",
|
|
21883
|
+
"reflectToAttr": true,
|
|
21884
|
+
"docs": "Specifies the corner geometry of the whole page: one of the `corner-shape`\nkeywords, or `default`.\n\nCorner geometry is theme appearance rather than an accessibility preference,\nwhich is why it lives here next to the theme name and scheme instead of in\n`mds-pref-mode`. Setting it writes `data-corner-shape` on `<html>`, where\nthe generated axis picks both the shape and the radius scale tuned for it.\n\nLeaving it unset touches nothing. Setting it to `default` REMOVES the\nattribute rather than writing today's default into the page, so a project\nthat never chose keeps following the design system when the default changes.",
|
|
21885
|
+
"docsTags": [],
|
|
21886
|
+
"values": [
|
|
21887
|
+
{
|
|
21888
|
+
"value": "bevel",
|
|
21889
|
+
"type": "string"
|
|
21890
|
+
},
|
|
21891
|
+
{
|
|
21892
|
+
"value": "default",
|
|
21893
|
+
"type": "string"
|
|
21894
|
+
},
|
|
21895
|
+
{
|
|
21896
|
+
"value": "notch",
|
|
21897
|
+
"type": "string"
|
|
21898
|
+
},
|
|
21899
|
+
{
|
|
21900
|
+
"value": "round",
|
|
21901
|
+
"type": "string"
|
|
21902
|
+
},
|
|
21903
|
+
{
|
|
21904
|
+
"value": "scoop",
|
|
21905
|
+
"type": "string"
|
|
21906
|
+
},
|
|
21907
|
+
{
|
|
21908
|
+
"value": "square",
|
|
21909
|
+
"type": "string"
|
|
21910
|
+
},
|
|
21911
|
+
{
|
|
21912
|
+
"value": "squircle",
|
|
21913
|
+
"type": "string"
|
|
21914
|
+
},
|
|
21915
|
+
{
|
|
21916
|
+
"type": "undefined"
|
|
21917
|
+
}
|
|
21918
|
+
],
|
|
21919
|
+
"optional": true,
|
|
21920
|
+
"required": false,
|
|
21921
|
+
"getter": false,
|
|
21922
|
+
"setter": false
|
|
21923
|
+
},
|
|
22126
21924
|
{
|
|
22127
21925
|
"name": "name",
|
|
22128
21926
|
"type": "string",
|
|
@@ -22236,30 +22034,7 @@
|
|
|
22236
22034
|
"setter": false
|
|
22237
22035
|
}
|
|
22238
22036
|
],
|
|
22239
|
-
"methods": [
|
|
22240
|
-
{
|
|
22241
|
-
"name": "updateLang",
|
|
22242
|
-
"returns": {
|
|
22243
|
-
"type": "Promise<void>",
|
|
22244
|
-
"docs": ""
|
|
22245
|
-
},
|
|
22246
|
-
"complexType": {
|
|
22247
|
-
"signature": "() => Promise<void>",
|
|
22248
|
-
"parameters": [],
|
|
22249
|
-
"references": {
|
|
22250
|
-
"Promise": {
|
|
22251
|
-
"location": "global",
|
|
22252
|
-
"id": "global::Promise"
|
|
22253
|
-
}
|
|
22254
|
-
},
|
|
22255
|
-
"return": "Promise<void>"
|
|
22256
|
-
},
|
|
22257
|
-
"signature": "updateLang() => Promise<void>",
|
|
22258
|
-
"parameters": [],
|
|
22259
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
22260
|
-
"docsTags": []
|
|
22261
|
-
}
|
|
22262
|
-
],
|
|
22037
|
+
"methods": [],
|
|
22263
22038
|
"events": [
|
|
22264
22039
|
{
|
|
22265
22040
|
"event": "mdsPrefChange",
|
|
@@ -22283,18 +22058,18 @@
|
|
|
22283
22058
|
"docsTags": []
|
|
22284
22059
|
},
|
|
22285
22060
|
{
|
|
22286
|
-
"event": "
|
|
22287
|
-
"detail": "
|
|
22061
|
+
"event": "mdsPrefThemeChange",
|
|
22062
|
+
"detail": "MdsPrefThemeEventDetail",
|
|
22288
22063
|
"bubbles": true,
|
|
22289
22064
|
"complexType": {
|
|
22290
|
-
"original": "
|
|
22291
|
-
"resolved": "
|
|
22065
|
+
"original": "MdsPrefThemeEventDetail",
|
|
22066
|
+
"resolved": "MdsPrefThemeEventDetail",
|
|
22292
22067
|
"references": {
|
|
22293
|
-
"
|
|
22068
|
+
"MdsPrefThemeEventDetail": {
|
|
22294
22069
|
"location": "import",
|
|
22295
|
-
"path": "@event/theme
|
|
22296
|
-
"id": "src/event-detail/theme
|
|
22297
|
-
"referenceLocation": "
|
|
22070
|
+
"path": "@event/theme",
|
|
22071
|
+
"id": "src/event-detail/theme.ts::MdsPrefThemeEventDetail",
|
|
22072
|
+
"referenceLocation": "MdsPrefThemeEventDetail"
|
|
22298
22073
|
}
|
|
22299
22074
|
}
|
|
22300
22075
|
},
|
|
@@ -22309,7 +22084,7 @@
|
|
|
22309
22084
|
"slots": [
|
|
22310
22085
|
{
|
|
22311
22086
|
"name": "",
|
|
22312
|
-
"docs": "Add `mds-pref-theme-
|
|
22087
|
+
"docs": "Add `mds-pref-theme-item` element/s."
|
|
22313
22088
|
}
|
|
22314
22089
|
],
|
|
22315
22090
|
"parts": [],
|
|
@@ -22322,7 +22097,7 @@
|
|
|
22322
22097
|
"mds-dropdown"
|
|
22323
22098
|
],
|
|
22324
22099
|
"dependencyGraph": {
|
|
22325
|
-
"mds-pref-theme
|
|
22100
|
+
"mds-pref-theme": [
|
|
22326
22101
|
"mds-text",
|
|
22327
22102
|
"mds-tab",
|
|
22328
22103
|
"mds-tab-item",
|
|
@@ -22339,16 +22114,16 @@
|
|
|
22339
22114
|
}
|
|
22340
22115
|
},
|
|
22341
22116
|
{
|
|
22342
|
-
"filePath": "src/components/mds-pref-theme-
|
|
22117
|
+
"filePath": "src/components/mds-pref-theme-item/mds-pref-theme-item.tsx",
|
|
22343
22118
|
"encapsulation": "shadow",
|
|
22344
|
-
"tag": "mds-pref-theme-
|
|
22345
|
-
"readme": "# mds-pref-theme-
|
|
22119
|
+
"tag": "mds-pref-theme-item",
|
|
22120
|
+
"readme": "# mds-pref-theme-item\n\n\n",
|
|
22346
22121
|
"docs": "",
|
|
22347
22122
|
"docsTags": [],
|
|
22348
22123
|
"usage": {
|
|
22349
|
-
"1. Description": "The `<mds-pref-theme-
|
|
22350
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref-theme-
|
|
22351
|
-
"3. Antipattern": "Common incorrect uses of `<mds-pref-theme-
|
|
22124
|
+
"1. Description": "The `<mds-pref-theme-item>` web component is a single selectable theme entry inside the [`<mds-pref-theme>`](../../mds-pref-theme) preference picker. It renders as a borderless button that pairs a color-swatch preview of the theme with its label.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-pref-theme>`; it is not used standalone or mixed with other child component types.\n- **Selection is parent-driven**: On click each item emits `mdsPrefThemeItemSelect` (carrying `{ name, scheme }`), and the parent responds by clearing the siblings and selecting the clicked one. Setting `selected` directly on a single item does not coordinate the others.\n- **Click bubbles up**: The emitted event is what the parent listens to in order to apply the theme to the document and persist the choice.\n- **Auto-derived label**: If `label` is omitted, it is generated from `name` by capitalizing the first letter and replacing hyphens with spaces (e.g. `maggioli-editore` becomes `Maggioli editore`).\n- **Static color preview**: The four swatches (primary, success, warning, error) are themed via CSS custom properties; they are not configurable through props.\n\n#### Properties & Visual Configurations\n\n- **`name`**: The theme identifier reported to the parent and matched against the parent's active `name` to compute initial selection. Use a simple or kebab-case string (e.g. `default`, `magma`, `maggioli-editore`); the parent validates the lowercase/kebab format and throws on invalid names.\n- **`scheme`**: Declares which color schemes the theme supports - `all` (default, both light and dark), or `light` / `dark` to force a single mode. This value travels with the selection event and is applied by the parent when the item is chosen.\n- **`selected`**: Reflects whether this item is the active theme. Prefer letting the parent manage it via selection rather than setting it manually on individual items.\n",
|
|
22125
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-pref-theme-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Usage Inside the Parent\n\n`<mds-pref-theme-item>` must always be a direct child of [`<mds-pref-theme>`](../../mds-pref-theme). Each item represents one selectable colour theme; the parent manages selection state so all siblings stay in sync.\n\n```html\n<mds-pref-theme name=\"default\" scheme=\"all\">\n <mds-pref-theme-item name=\"default\" label=\"Predefinito\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"magma\" label=\"Magma\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"maggioli-editore\" label=\"Maggioli Editore\" scheme=\"all\"></mds-pref-theme-item>\n</mds-pref-theme>\n```\n\n#### Auto-Derived Label\n\nOmit `label` and let the component generate it from `name`: the first letter is capitalised and hyphens are replaced with spaces. Use this shorthand when the theme name is already human-readable.\n\n```html\n<mds-pref-theme name=\"default\" scheme=\"all\">\n <!-- renders \"Default\", \"Summer\", \"Twilight\" without explicit label props -->\n <mds-pref-theme-item name=\"default\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"summer\" scheme=\"light\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"twilight\" scheme=\"dark\"></mds-pref-theme-item>\n</mds-pref-theme>\n```\n\n#### Scheme-Specific Themes\n\nSet `scheme` to `\"light\"` or `\"dark\"` when a theme is designed for a single colour mode only. The parent applies the forced mode when the item is selected.\n\n```html\n<mds-pref-theme name=\"default\" scheme=\"all\">\n <!-- this theme works in both modes -->\n <mds-pref-theme-item name=\"default\" label=\"Predefinito\" scheme=\"all\"></mds-pref-theme-item>\n\n <!-- this theme is light-only; selecting it locks the UI in light mode -->\n <mds-pref-theme-item name=\"estate\" label=\"Estate\" scheme=\"light\"></mds-pref-theme-item>\n\n <!-- this theme is dark-only; selecting it locks the UI in dark mode -->\n <mds-pref-theme-item name=\"notte\" label=\"Notte\" scheme=\"dark\"></mds-pref-theme-item>\n</mds-pref-theme>\n```\n\n#### Listening to the Selection Event\n\nAttach a listener for `mdsPrefThemeItemSelect` when you need to react to a selection at the item level - for example to log analytics. The detail carries `{ name, scheme }`. Normally the parent handles theme application automatically; only listen at this level for side-effects.\n\n```html\n<mds-pref-theme name=\"default\" scheme=\"all\">\n <mds-pref-theme-item name=\"default\" label=\"Predefinito\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"magma\" label=\"Magma\" scheme=\"all\"></mds-pref-theme-item>\n</mds-pref-theme>\n\n<script>\n document.querySelectorAll('mds-pref-theme-item').forEach((item) => {\n item.addEventListener('mdsPrefThemeItemSelect', (e) => {\n console.log('Tema selezionato:', e.detail.name, 'schema:', e.detail.scheme);\n });\n });\n</script>\n```\n\n#### Setting the Initially Selected Item\n\nSet `selected` on the item that matches the user's saved preference before the component renders. The parent will sync the rest of the items automatically once it receives the selection event on first interaction.\n\n```html\n<mds-pref-theme name=\"magma\" scheme=\"all\">\n <mds-pref-theme-item name=\"default\" label=\"Predefinito\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"magma\" label=\"Magma\" scheme=\"all\" selected></mds-pref-theme-item>\n <mds-pref-theme-item name=\"notte\" label=\"Notte\" scheme=\"dark\"></mds-pref-theme-item>\n</mds-pref-theme>\n```\n\n#### CSS Customization via Documented Properties\n\nOverride the swatch colours only through the documented `--mds-pref-theme-item-*` CSS custom properties. Set them on the host element or a parent selector and use Magma token wrappers for colour values so dark mode keeps working.\n\n```css\n/* override the colour preview dots for a custom \"brand\" theme item */\nmds-pref-theme-item[name=\"brand\"] {\n --mds-pref-theme-item-color-variant-primary: rgb(var(--variant-secondary-03));\n --mds-pref-theme-item-color-status-success: rgb(var(--status-success-05));\n --mds-pref-theme-item-color-status-warning: rgb(var(--status-warning-05));\n --mds-pref-theme-item-color-status-error: rgb(var(--status-error-05));\n --mds-pref-theme-item-color-background: rgb(var(--tone-neutral-08));\n}\n```\n",
|
|
22126
|
+
"3. Antipattern": "Common incorrect uses of `<mds-pref-theme-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use the Item Outside Its Parent\n\n`<mds-pref-theme-item>` is a compound child that must be a direct slot child of [`<mds-pref-theme>`](../../mds-pref-theme). Used standalone it emits selection events that are never handled, and it never receives coordinated deselection of siblings.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-theme-item name=\"magma\" label=\"Magma\" scheme=\"all\"></mds-pref-theme-item>\n\n<!-- ✅ CORRECT -->\n<mds-pref-theme name=\"default\" scheme=\"all\">\n <mds-pref-theme-item name=\"magma\" label=\"Magma\" scheme=\"all\"></mds-pref-theme-item>\n</mds-pref-theme>\n```\n\n#### Do Not Set `selected` Manually to Coordinate Multi-Item State\n\nSetting `selected` on one item does not deselect the others - the parent is the only actor that can coordinate the whole group. Drive initial selection through the parent's `name` prop or by letting the user click.\n\n```html\n<!-- 🚫 INCORRECT - only one item will visually appear selected; siblings are unaffected -->\n<mds-pref-theme name=\"default\" scheme=\"all\">\n <mds-pref-theme-item name=\"default\" label=\"Predefinito\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"magma\" label=\"Magma\" scheme=\"all\" selected></mds-pref-theme-item>\n <mds-pref-theme-item name=\"notte\" label=\"Notte\" scheme=\"dark\" selected></mds-pref-theme-item>\n</mds-pref-theme>\n\n<!-- ✅ CORRECT - set the active theme on the parent; it marks the matching child -->\n<mds-pref-theme name=\"magma\" scheme=\"all\">\n <mds-pref-theme-item name=\"default\" label=\"Predefinito\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"magma\" label=\"Magma\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"notte\" label=\"Notte\" scheme=\"dark\"></mds-pref-theme-item>\n</mds-pref-theme>\n```\n\n#### Do Not Listen for Native `click` Instead of the Component Event\n\nThe inner `<mds-button>` is inside shadow DOM and a raw `click` listener on the host may fire in unexpected order or not at all across frameworks. Listen for the documented `mdsPrefThemeItemSelect` event instead.\n\n```html\n<!-- 🚫 INCORRECT -->\n<script>\n document.querySelector('mds-pref-theme-item').addEventListener('click', (e) => {\n applyTheme(e.target.getAttribute('name'));\n });\n</script>\n\n<!-- ✅ CORRECT -->\n<script>\n document.querySelector('mds-pref-theme-item').addEventListener('mdsPrefThemeItemSelect', (e) => {\n applyTheme(e.detail.name);\n });\n</script>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Inner Button\n\nThe supported customization surface is the five `--mds-pref-theme-item-*` CSS custom properties. Targeting internal selectors or `::part()` names not present in this component's public API couples your code to the implementation and will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-pref-theme-item >>> mds-button {\n font-weight: bold;\n}\nmds-pref-theme-item .theme-preview {\n border: 2px solid red;\n}\n\n/* ✅ CORRECT */\nmds-pref-theme-item[name=\"brand\"] {\n --mds-pref-theme-item-color-variant-primary: rgb(var(--variant-secondary-03));\n --mds-pref-theme-item-color-background: rgb(var(--tone-neutral-08));\n}\n```\n\n#### Do Not Use an Invalid `scheme` Value\n\n`scheme` only accepts `\"all\"`, `\"light\"`, or `\"dark\"`. Other strings silently fall back and the parent may apply the wrong mode when the item is selected.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-pref-theme-item name=\"estate\" scheme=\"light-only\"></mds-pref-theme-item>\n<mds-pref-theme-item name=\"notte\" scheme=\"night\"></mds-pref-theme-item>\n\n<!-- ✅ CORRECT -->\n<mds-pref-theme-item name=\"estate\" scheme=\"light\"></mds-pref-theme-item>\n<mds-pref-theme-item name=\"notte\" scheme=\"dark\"></mds-pref-theme-item>\n```\n"
|
|
22352
22127
|
},
|
|
22353
22128
|
"props": [
|
|
22354
22129
|
{
|
|
@@ -22487,44 +22262,21 @@
|
|
|
22487
22262
|
"setter": false
|
|
22488
22263
|
}
|
|
22489
22264
|
],
|
|
22490
|
-
"methods": [
|
|
22491
|
-
{
|
|
22492
|
-
"name": "updateLang",
|
|
22493
|
-
"returns": {
|
|
22494
|
-
"type": "Promise<void>",
|
|
22495
|
-
"docs": ""
|
|
22496
|
-
},
|
|
22497
|
-
"complexType": {
|
|
22498
|
-
"signature": "() => Promise<void>",
|
|
22499
|
-
"parameters": [],
|
|
22500
|
-
"references": {
|
|
22501
|
-
"Promise": {
|
|
22502
|
-
"location": "global",
|
|
22503
|
-
"id": "global::Promise"
|
|
22504
|
-
}
|
|
22505
|
-
},
|
|
22506
|
-
"return": "Promise<void>"
|
|
22507
|
-
},
|
|
22508
|
-
"signature": "updateLang() => Promise<void>",
|
|
22509
|
-
"parameters": [],
|
|
22510
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
22511
|
-
"docsTags": []
|
|
22512
|
-
}
|
|
22513
|
-
],
|
|
22265
|
+
"methods": [],
|
|
22514
22266
|
"events": [
|
|
22515
22267
|
{
|
|
22516
|
-
"event": "
|
|
22517
|
-
"detail": "
|
|
22268
|
+
"event": "mdsPrefThemeItemSelect",
|
|
22269
|
+
"detail": "MdsPrefThemeEventDetail",
|
|
22518
22270
|
"bubbles": true,
|
|
22519
22271
|
"complexType": {
|
|
22520
|
-
"original": "
|
|
22521
|
-
"resolved": "
|
|
22272
|
+
"original": "MdsPrefThemeEventDetail",
|
|
22273
|
+
"resolved": "MdsPrefThemeEventDetail",
|
|
22522
22274
|
"references": {
|
|
22523
|
-
"
|
|
22275
|
+
"MdsPrefThemeEventDetail": {
|
|
22524
22276
|
"location": "import",
|
|
22525
|
-
"path": "@event/theme
|
|
22526
|
-
"id": "src/event-detail/theme
|
|
22527
|
-
"referenceLocation": "
|
|
22277
|
+
"path": "@event/theme",
|
|
22278
|
+
"id": "src/event-detail/theme.ts::MdsPrefThemeEventDetail",
|
|
22279
|
+
"referenceLocation": "MdsPrefThemeEventDetail"
|
|
22528
22280
|
}
|
|
22529
22281
|
}
|
|
22530
22282
|
},
|
|
@@ -22537,27 +22289,27 @@
|
|
|
22537
22289
|
"listeners": [],
|
|
22538
22290
|
"styles": [
|
|
22539
22291
|
{
|
|
22540
|
-
"name": "--mds-pref-theme-
|
|
22292
|
+
"name": "--mds-pref-theme-item-color-background",
|
|
22541
22293
|
"annotation": "prop",
|
|
22542
|
-
"docs": "Background color of a theme
|
|
22294
|
+
"docs": "Background color of a theme item."
|
|
22543
22295
|
},
|
|
22544
22296
|
{
|
|
22545
|
-
"name": "--mds-pref-theme-
|
|
22297
|
+
"name": "--mds-pref-theme-item-color-status-error",
|
|
22546
22298
|
"annotation": "prop",
|
|
22547
|
-
"docs": "Color representing an error status for a
|
|
22299
|
+
"docs": "Color representing an error status for a theme item."
|
|
22548
22300
|
},
|
|
22549
22301
|
{
|
|
22550
|
-
"name": "--mds-pref-theme-
|
|
22302
|
+
"name": "--mds-pref-theme-item-color-status-success",
|
|
22551
22303
|
"annotation": "prop",
|
|
22552
|
-
"docs": "Color representing a success status for a
|
|
22304
|
+
"docs": "Color representing a success status for a theme item."
|
|
22553
22305
|
},
|
|
22554
22306
|
{
|
|
22555
|
-
"name": "--mds-pref-theme-
|
|
22307
|
+
"name": "--mds-pref-theme-item-color-status-warning",
|
|
22556
22308
|
"annotation": "prop",
|
|
22557
|
-
"docs": "Color representing a warning status for a
|
|
22309
|
+
"docs": "Color representing a warning status for a theme item."
|
|
22558
22310
|
},
|
|
22559
22311
|
{
|
|
22560
|
-
"name": "--mds-pref-theme-
|
|
22312
|
+
"name": "--mds-pref-theme-item-color-variant-primary",
|
|
22561
22313
|
"annotation": "prop",
|
|
22562
22314
|
"docs": "Color for the primary variant item."
|
|
22563
22315
|
}
|
|
@@ -22570,7 +22322,7 @@
|
|
|
22570
22322
|
"mds-button"
|
|
22571
22323
|
],
|
|
22572
22324
|
"dependencyGraph": {
|
|
22573
|
-
"mds-pref-theme-
|
|
22325
|
+
"mds-pref-theme-item": [
|
|
22574
22326
|
"mds-button"
|
|
22575
22327
|
],
|
|
22576
22328
|
"mds-button": [
|
|
@@ -23044,7 +22796,7 @@
|
|
|
23044
22796
|
],
|
|
23045
22797
|
"usage": {
|
|
23046
22798
|
"1. Description": "The `<mds-price-table-list-item>` web component represents a single feature row inside a [`<mds-price-table-list>`](../../mds-price-table-list), pairing a supported/unsupported status icon with a textual feature label. It is a presentational compound child.\n\n#### Semantic Behavior\n\n- **Compound child only**: It auto-assigns itself to the parent's `item` slot, so it must be a direct child of `<mds-price-table-list>` and is not used standalone.\n- **Drives parent layout**: The presence of at least one item is what makes the parent render its separator and feature region.\n- **Status icon by `supported`**: When `supported` is `true` it renders a filled check-circle icon; when `false` it renders a horizontal-rule (dash) icon, indicating the feature is absent.\n- **Default slot is the label**: Text or markup placed in the default slot becomes the feature description, rendered next to the icon.\n- **No interactivity**: The component is purely presentational - it has no role, selection/active/disabled state, emitted events, or keyboard handling.\n\n#### Properties & Visual Configurations\n\n- **`supported`**: Choose `true` for features included in the plan (check icon) and `false` for features not included (dash icon). It is the only semantic switch that changes the rendered icon, and is themeable via the `--mds-price-table-list-item-supported-*` / `-unsupported-*` CSS custom properties.\n- **`typography`**: Selects the text scale applied to both the icon wrapper and the label, accepting one of the shared read typography tokens (default `detail`). Use a larger value such as `paragraph` when the list should read at body size, or `caption` for denser tables.\n",
|
|
23047
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-price-table-list-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Supported Feature Row\n\nThe most common form. Place the component as a direct child of [`<mds-price-table-list>`](../../mds-price-table-list) and set `supported` to show the check-circle icon. Text in the default slot becomes the feature label.\n\n```html\n<mds-price-table-list>\n <mds-price-table-list-item supported>Accesso base</mds-price-table-list-item>\n</mds-price-table-list>\n```\n\n#### Unsupported Feature Row\n\nOmit `supported` (or leave it at its default `false`) to render the dash icon, indicating the feature is not included in the plan.\n\n```html\n<mds-price-table-list>\n <mds-price-table-list-item>Accesso API</mds-price-table-list-item>\n</mds-price-table-list>\n```\n\n#### Mixed Feature List\n\nCombine supported and unsupported rows inside one `<mds-price-table-list>` to build the complete plan comparison column.\n\n```html\n<mds-price-table-list>\n <mds-price-table-list-item supported>Utenti illimitati</mds-price-table-list-item>\n <mds-price-table-list-item supported>Supporto via chat</mds-price-table-list-item>\n <mds-price-table-list-item supported>Flussi automatizzati</mds-price-table-list-item>\n <mds-price-table-list-item>Analisi avanzata</mds-price-table-list-item>\n <mds-price-table-list-item>Esportazione report</mds-price-table-list-item>\n <mds-price-table-list-item>Accesso API</mds-price-table-list-item>\n</mds-price-table-list>\n```\n\n#### Feature Row with Contextual Help\n\nThe default slot accepts more than plain text. Slot an [`<mds-help>`](../../mds-help) inline next to the label when a feature needs a short explanation.\n\n```html\n<mds-price-table-list>\n <mds-price-table-list-item supported>\n 20 GB di spazio per utente\n <mds-help>Lo spazio viene condiviso fra tutti i membri del piano.</mds-help>\n </mds-price-table-list-item>\n</mds-price-table-list>\n```\n\n#### Adjusting Typography Scale\n\nUse the `typography` prop to control text and icon size across the whole row. The default `detail` fits dense tables; switch to `paragraph` for a more readable presentation or `caption` for compact layouts.\n\n```html\n<!-- Default (detail) -->\n<mds-price-table-list-item supported>Funzionalita di base</mds-price-table-list-item>\n\n<!-- Body-size presentation -->\n<mds-price-table-list-item supported typography=\"paragraph\">Funzionalita di base</mds-price-table-list-item>\n\n<!-- Compact table -->\n<mds-price-table-list-item typography=\"caption\">Accesso API</mds-price-table-list-item>\n```\n\n#### Full Plan Column\n\nThe full compound pattern: `<mds-price-table-list>` with header, items, a price, and a call-to-action.\n\n```html\n<mds-price-table-list>\n <mds-text typography=\"h5\" slot=\"header\">Piano Business</mds-text>\n <mds-text typography=\"detail\" slot=\"header\">\n Adatto a team di medie dimensioni con esigenze collaborative avanzate.\n </mds-text>\n\n <mds-price-table-list-item supported>Utenti illimitati</mds-price-table-list-item>\n <mds-price-table-list-item supported>Supporto prioritario</mds-price-table-list-item>\n <mds-price-table-list-item supported>Flussi automatizzati</mds-price-table-list-item>\n <mds-price-table-list-item>Accesso API</mds-price-table-list-item>\n\n <mds-text typography=\"h2\" slot=\"price\">99 EUR</mds-text>\n <mds-button slot=\"action\" variant=\"primary\" tone=\"strong\">Inizia ora</mds-button>\n</mds-price-table-list>\n```\n\n#### Styling Customization\n\nOverride the icon colors only through the documented `--mds-price-table-list-item-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast keep working.\n\n```css\n.promo-column mds-price-table-list-item {\n --mds-price-table-list-item-supported-icon-color: rgb(var(--variant-primary-05));\n --mds-price-table-list-item-supported-icon-color-hover: rgb(var(--variant-primary-04));\n --mds-price-table-list-item-unsupported-icon-color: rgb(var(--tone-neutral-06));\n
|
|
22799
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-price-table-list-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Supported Feature Row\n\nThe most common form. Place the component as a direct child of [`<mds-price-table-list>`](../../mds-price-table-list) and set `supported` to show the check-circle icon. Text in the default slot becomes the feature label.\n\n```html\n<mds-price-table-list>\n <mds-price-table-list-item supported>Accesso base</mds-price-table-list-item>\n</mds-price-table-list>\n```\n\n#### Unsupported Feature Row\n\nOmit `supported` (or leave it at its default `false`) to render the dash icon, indicating the feature is not included in the plan.\n\n```html\n<mds-price-table-list>\n <mds-price-table-list-item>Accesso API</mds-price-table-list-item>\n</mds-price-table-list>\n```\n\n#### Mixed Feature List\n\nCombine supported and unsupported rows inside one `<mds-price-table-list>` to build the complete plan comparison column.\n\n```html\n<mds-price-table-list>\n <mds-price-table-list-item supported>Utenti illimitati</mds-price-table-list-item>\n <mds-price-table-list-item supported>Supporto via chat</mds-price-table-list-item>\n <mds-price-table-list-item supported>Flussi automatizzati</mds-price-table-list-item>\n <mds-price-table-list-item>Analisi avanzata</mds-price-table-list-item>\n <mds-price-table-list-item>Esportazione report</mds-price-table-list-item>\n <mds-price-table-list-item>Accesso API</mds-price-table-list-item>\n</mds-price-table-list>\n```\n\n#### Feature Row with Contextual Help\n\nThe default slot accepts more than plain text. Slot an [`<mds-help>`](../../mds-help) inline next to the label when a feature needs a short explanation.\n\n```html\n<mds-price-table-list>\n <mds-price-table-list-item supported>\n 20 GB di spazio per utente\n <mds-help>Lo spazio viene condiviso fra tutti i membri del piano.</mds-help>\n </mds-price-table-list-item>\n</mds-price-table-list>\n```\n\n#### Adjusting Typography Scale\n\nUse the `typography` prop to control text and icon size across the whole row. The default `detail` fits dense tables; switch to `paragraph` for a more readable presentation or `caption` for compact layouts.\n\n```html\n<!-- Default (detail) -->\n<mds-price-table-list-item supported>Funzionalita di base</mds-price-table-list-item>\n\n<!-- Body-size presentation -->\n<mds-price-table-list-item supported typography=\"paragraph\">Funzionalita di base</mds-price-table-list-item>\n\n<!-- Compact table -->\n<mds-price-table-list-item typography=\"caption\">Accesso API</mds-price-table-list-item>\n```\n\n#### Full Plan Column\n\nThe full compound pattern: `<mds-price-table-list>` with header, items, a price, and a call-to-action.\n\n```html\n<mds-price-table-list>\n <mds-text typography=\"h5\" slot=\"header\">Piano Business</mds-text>\n <mds-text typography=\"detail\" slot=\"header\">\n Adatto a team di medie dimensioni con esigenze collaborative avanzate.\n </mds-text>\n\n <mds-price-table-list-item supported>Utenti illimitati</mds-price-table-list-item>\n <mds-price-table-list-item supported>Supporto prioritario</mds-price-table-list-item>\n <mds-price-table-list-item supported>Flussi automatizzati</mds-price-table-list-item>\n <mds-price-table-list-item>Accesso API</mds-price-table-list-item>\n\n <mds-text typography=\"h2\" slot=\"price\">99 EUR</mds-text>\n <mds-button slot=\"action\" variant=\"primary\" tone=\"strong\">Inizia ora</mds-button>\n</mds-price-table-list>\n```\n\n#### Styling Customization\n\nOverride the icon colors only through the documented `--mds-price-table-list-item-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast keep working.\n\n```css\n.promo-column mds-price-table-list-item {\n --mds-price-table-list-item-supported-icon-color: rgb(var(--variant-primary-05));\n --mds-price-table-list-item-supported-icon-color-hover: rgb(var(--variant-primary-04));\n --mds-price-table-list-item-unsupported-icon-color: rgb(var(--tone-neutral-06));\n}\n```\n",
|
|
23048
22800
|
"3. Antipattern": "Common incorrect uses of `<mds-price-table-list-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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use Outside `<mds-price-table-list>`\n\nThe component auto-assigns itself to the parent's `item` slot and is designed exclusively as a child of [`<mds-price-table-list>`](../../mds-price-table-list). Using it standalone produces unstyled output and the icon region becomes orphaned.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-price-table-list-item supported>Funzionalita inclusa</mds-price-table-list-item>\n\n<!-- ✅ CORRECT -->\n<mds-price-table-list>\n <mds-price-table-list-item supported>Funzionalita inclusa</mds-price-table-list-item>\n</mds-price-table-list>\n```\n\n#### Do Not Pass `supported` as a String\n\n`supported` is a boolean prop. Setting `supported=\"false\"` is not the same as omitting it - any non-empty string is truthy in HTML, so the check-circle icon appears even though you intended the unsupported state. Remove the attribute to turn the feature off.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-price-table-list-item supported=\"false\">Accesso API</mds-price-table-list-item>\n\n<!-- ✅ CORRECT -->\n<mds-price-table-list-item>Accesso API</mds-price-table-list-item>\n```\n\n#### Do Not Use an Unsupported `typography` Value\n\n`typography` accepts only `\"caption\"`, `\"detail\"`, and `\"paragraph\"` (the `TypographyReadType` set). Passing a value outside that set - such as `\"h4\"` or `\"label\"` - produces no error but silently breaks the layout because `mds-text` will not recognise the scale.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-price-table-list-item typography=\"h4\" supported>Accesso base</mds-price-table-list-item>\n<mds-price-table-list-item typography=\"label\">Analytics</mds-price-table-list-item>\n\n<!-- ✅ CORRECT -->\n<mds-price-table-list-item typography=\"paragraph\" supported>Accesso base</mds-price-table-list-item>\n<mds-price-table-list-item typography=\"caption\">Analytics</mds-price-table-list-item>\n```\n\n#### Do Not Pierce the Shadow DOM to Restyle the Icon\n\nThe only supported customization surface for the icon is the four `--mds-price-table-list-item-*` CSS custom properties and the documented `::part(icon)` shadow part. Targeting internal selectors via `>>>`, `/deep/`, or undocumented class names couples your styles to the implementation and will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-price-table-list-item >>> .icon {\n fill: green;\n}\n\n/* ✅ CORRECT */\nmds-price-table-list-item {\n --mds-price-table-list-item-supported-icon-color: rgb(var(--variant-success-05));\n}\n/* or, for targeted SVG fill overrides: */\nmds-price-table-list-item::part(icon) {\n fill: rgb(var(--variant-success-05));\n}\n```\n\n#### Do Not Put Block HTML in the Default Slot to Create Layout\n\nThe default slot is for the feature label - plain text plus inline helpers such as `<mds-help>`. Inserting block elements, additional icons, or wrapper `<div>` structures breaks the flex row layout that aligns the icon and label.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-price-table-list-item supported>\n <div class=\"feature-row\">\n <mds-icon name=\"mi/baseline/star\"></mds-icon>\n <span>Analisi avanzata</span>\n </div>\n</mds-price-table-list-item>\n\n<!-- ✅ CORRECT -->\n<mds-price-table-list-item supported>\n Analisi avanzata\n <mds-help>Disponibile solo nei piani premium.</mds-help>\n</mds-price-table-list-item>\n```\n"
|
|
23049
22801
|
},
|
|
23050
22802
|
"props": [
|
|
@@ -23141,11 +22893,6 @@
|
|
|
23141
22893
|
"name": "--mds-price-table-list-item-unsupported-icon-color",
|
|
23142
22894
|
"annotation": "prop",
|
|
23143
22895
|
"docs": "Default color of the unsupported icon in a list item."
|
|
23144
|
-
},
|
|
23145
|
-
{
|
|
23146
|
-
"name": "--mds-price-table-list-item-unsupported-icon-color-hover",
|
|
23147
|
-
"annotation": "prop",
|
|
23148
|
-
"docs": "Color of the unsupported icon in a list item on hover."
|
|
23149
22896
|
}
|
|
23150
22897
|
],
|
|
23151
22898
|
"slots": [
|
|
@@ -23189,7 +22936,7 @@
|
|
|
23189
22936
|
],
|
|
23190
22937
|
"usage": {
|
|
23191
22938
|
"1. Description": "The `<mds-progress>` web component is the progress indicator of the Magma Design System, rendering the completion state of a determinate task as a bar or ring. It is the system equivalent of the native HTML `<progress>` element, exposing the appropriate progressbar role and ARIA value attributes natively.\n\n#### Semantic Behavior\n\n- **Spoken step text**: As `progress` changes, the component maps the value onto the `steps` list and announces the matching label, so assistive technologies report a human-readable milestone rather than a raw number.\n- **Decorative opt-out**: When the host carries `aria-hidden=\"true\"`, all progressbar semantics are stripped so the indicator can be used as purely decorative chrome.\n- **Radial delegation**: With `direction=\"radial\"` the rendering is delegated to `mds-radial-progress`, which carries the typography and the textual percentage; the bar directions render a single fill instead.\n\n#### Properties & Visual Configurations\n\n- **`progress`** is the source of truth: a fractional value between `0` and `1` (not a percentage) that drives both the visual fill and the computed ARIA value.\n- **`steps`** is a comma-separated string of milestone labels (default Italian: `'Inizio,Un quarto,Metà,Tre quarti,Fine'`); the current `progress` is quantized across these labels to pick what screen readers announce. Provide labels that match the granularity of the task.\n- **`typography`** (`'option'` | `'label'`) selects the type scale applied to the textual percentage shown inside the radial variant; it has no effect on the bar directions.\n\n#### Other behavioral props\n\n- **`direction`** chooses the geometry: `'horizontal'` and `'vertical'` render a linear fill bar, while `'radial'` renders a circular ring with a centered percentage via `mds-radial-progress`.\n\nThe shared `variant` and `size` ladders are defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); this component adds no values beyond the shared sets.\n",
|
|
23192
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-progress>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Horizontal Progress Bar\n\nThe default form. Pass `progress` as a fractional value between `0` and `1`. The component exposes `role=\"progressbar\"` and manages `aria-valuenow` automatically.\n\n```html\n<mds-progress progress=\"0.4\" aria-label=\"Caricamento documento\"></mds-progress>\n```\n\n#### Variant for Semantic Meaning\n\nUse `variant` to communicate the nature of the task - not just the colour you want. The component maps every `ThemeVariantType` value to a matching color pair for the fill and track.\n\n```html\n<!-- Operazione riuscita -->\n<mds-progress progress=\"1\" variant=\"success\" aria-label=\"Importazione completata\"></mds-progress>\n\n<!-- Operazione con avviso -->\n<mds-progress progress=\"0.6\" variant=\"warning\" aria-label=\"Quota disco in esaurimento\"></mds-progress>\n\n<!-- Errore -->\n<mds-progress progress=\"0.85\" variant=\"error\" aria-label=\"Errore di rete\"></mds-progress>\n\n<!-- Contenuto AI -->\n<mds-progress progress=\"0.5\" variant=\"ai\" aria-label=\"Elaborazione AI in corso\"></mds-progress>\n```\n\n#### Sizing\n\nUse the `size` prop to control the thickness of the bar. `sm` is the default and suits most inline uses; larger values give more visual weight in dashboard or hero contexts.\n\n```html\n<mds-progress progress=\"0.5\" size=\"sm\" aria-label=\"Piccola barra\"></mds-progress>\n<mds-progress progress=\"0.5\" size=\"md\" aria-label=\"Barra media\"></mds-progress>\n<mds-progress progress=\"0.5\" size=\"lg\" aria-label=\"Barra grande\"></mds-progress>\n<mds-progress progress=\"0.5\" size=\"xl\" aria-label=\"Barra extra grande\"></mds-progress>\n```\n\n#### Vertical Progress Bar\n\nSet `direction=\"vertical\"` for upward-fill layouts such as column charts or skill meters. Give the host an explicit height via CSS because the element stretches to fit its container.\n\n```html\n<mds-progress\n progress=\"0.65\"\n direction=\"vertical\"\n variant=\"primary\"\n aria-label=\"Utilizzo CPU\"\n style=\"height: 120px;\"\n></mds-progress>\n```\n\n#### Radial Progress Bar\n\nSet `direction=\"radial\"` to render a circular ring with a centered percentage label via the internal `mds-radial-progress` component. Control the ring diameter through a CSS width on the host.\n\n```html\n<mds-progress\n progress=\"0.72\"\n direction=\"radial\"\n variant=\"primary\"\n aria-label=\"Completamento profilo\"\n style=\"width: 80px;\"\n></mds-progress>\n```\n\n#### Radial with Typography Control\n\nWhen `direction=\"radial\"`, the `typography` prop selects the type scale applied to the centered percentage label. Use `'label'` for denser layouts and `'option'` (default) for standard sizing.\n\n```html\n<mds-progress\n progress=\"0.5\"\n direction=\"radial\"\n typography=\"label\"\n aria-label=\"Avanzamento attivita\"\n style=\"width: 64px;\"\n></mds-progress>\n```\n\n#### Accessible Step Labels\n\nThe `steps` prop is a comma-separated list of milestone strings. As `progress` changes the component picks the nearest label and sets `aria-valuetext`, so screen readers announce a meaningful milestone rather than a raw number. Provide labels that match the granularity of your task.\n\n```html\n<mds-progress\n progress=\"0.5\"\n steps=\"Inizializzazione,Analisi,Elaborazione,Completamento\"\n variant=\"primary\"\n aria-label=\"Avanzamento analisi dati\"\n></mds-progress>\n```\n\n#### Decorative Use (aria-hidden)\n\nWhen `<mds-progress>` is used purely as a visual indicator alongside a separate text description, set `aria-hidden=\"true\"`. The component removes all progressbar ARIA attributes so assistive technologies skip it.\n\n```html\n<p>Progresso: 40%</p>\n<mds-progress progress=\"0.4\" aria-hidden=\"true\"></mds-progress>\n```\n\n#### Updating Progress Dynamically\n\nSet the `progress` attribute from JavaScript as the task advances. The component transitions the fill with `--mds-progress-duration` and updates `aria-valuenow` and `aria-valuetext` on each change.\n\n```javascript\nconst bar = document.querySelector('mds-progress');\n\nasync function runTask() {\n for (let i = 0; i <= 10; i++) {\n await doWork(i);\n bar.progress = i / 10;\n }\n}\n```\n\n#### Styling Customization\n\nOverride the documented `--mds-progress-*` CSS custom properties for one-off visual tweaks. Use Magma color tokens via `rgb(var(--<token>))` so dark mode keeps working.\n\n```css\n.upload-widget mds-progress {\n --mds-progress-background: rgb(var(--tone-neutral-09));\n --mds-progress-color: rgb(var(--variant-secondary-03));\n --mds-progress-thickness:
|
|
22939
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-progress>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Horizontal Progress Bar\n\nThe default form. Pass `progress` as a fractional value between `0` and `1`. The component exposes `role=\"progressbar\"` and manages `aria-valuenow` automatically.\n\n```html\n<mds-progress progress=\"0.4\" aria-label=\"Caricamento documento\"></mds-progress>\n```\n\n#### Variant for Semantic Meaning\n\nUse `variant` to communicate the nature of the task - not just the colour you want. The component maps every `ThemeVariantType` value to a matching color pair for the fill and track.\n\n```html\n<!-- Operazione riuscita -->\n<mds-progress progress=\"1\" variant=\"success\" aria-label=\"Importazione completata\"></mds-progress>\n\n<!-- Operazione con avviso -->\n<mds-progress progress=\"0.6\" variant=\"warning\" aria-label=\"Quota disco in esaurimento\"></mds-progress>\n\n<!-- Errore -->\n<mds-progress progress=\"0.85\" variant=\"error\" aria-label=\"Errore di rete\"></mds-progress>\n\n<!-- Contenuto AI -->\n<mds-progress progress=\"0.5\" variant=\"ai\" aria-label=\"Elaborazione AI in corso\"></mds-progress>\n```\n\n#### Sizing\n\nUse the `size` prop to control the thickness of the bar. `sm` is the default and suits most inline uses; larger values give more visual weight in dashboard or hero contexts.\n\n```html\n<mds-progress progress=\"0.5\" size=\"sm\" aria-label=\"Piccola barra\"></mds-progress>\n<mds-progress progress=\"0.5\" size=\"md\" aria-label=\"Barra media\"></mds-progress>\n<mds-progress progress=\"0.5\" size=\"lg\" aria-label=\"Barra grande\"></mds-progress>\n<mds-progress progress=\"0.5\" size=\"xl\" aria-label=\"Barra extra grande\"></mds-progress>\n```\n\n#### Vertical Progress Bar\n\nSet `direction=\"vertical\"` for upward-fill layouts such as column charts or skill meters. Give the host an explicit height via CSS because the element stretches to fit its container.\n\n```html\n<mds-progress\n progress=\"0.65\"\n direction=\"vertical\"\n variant=\"primary\"\n aria-label=\"Utilizzo CPU\"\n style=\"height: 120px;\"\n></mds-progress>\n```\n\n#### Radial Progress Bar\n\nSet `direction=\"radial\"` to render a circular ring with a centered percentage label via the internal `mds-radial-progress` component. Control the ring diameter through a CSS width on the host.\n\n```html\n<mds-progress\n progress=\"0.72\"\n direction=\"radial\"\n variant=\"primary\"\n aria-label=\"Completamento profilo\"\n style=\"width: 80px;\"\n></mds-progress>\n```\n\n#### Radial with Typography Control\n\nWhen `direction=\"radial\"`, the `typography` prop selects the type scale applied to the centered percentage label. Use `'label'` for denser layouts and `'option'` (default) for standard sizing.\n\n```html\n<mds-progress\n progress=\"0.5\"\n direction=\"radial\"\n typography=\"label\"\n aria-label=\"Avanzamento attivita\"\n style=\"width: 64px;\"\n></mds-progress>\n```\n\n#### Accessible Step Labels\n\nThe `steps` prop is a comma-separated list of milestone strings. As `progress` changes the component picks the nearest label and sets `aria-valuetext`, so screen readers announce a meaningful milestone rather than a raw number. Provide labels that match the granularity of your task.\n\n```html\n<mds-progress\n progress=\"0.5\"\n steps=\"Inizializzazione,Analisi,Elaborazione,Completamento\"\n variant=\"primary\"\n aria-label=\"Avanzamento analisi dati\"\n></mds-progress>\n```\n\n#### Decorative Use (aria-hidden)\n\nWhen `<mds-progress>` is used purely as a visual indicator alongside a separate text description, set `aria-hidden=\"true\"`. The component removes all progressbar ARIA attributes so assistive technologies skip it.\n\n```html\n<p>Progresso: 40%</p>\n<mds-progress progress=\"0.4\" aria-hidden=\"true\"></mds-progress>\n```\n\n#### Updating Progress Dynamically\n\nSet the `progress` attribute from JavaScript as the task advances. The component transitions the fill with `--mds-progress-duration` and updates `aria-valuenow` and `aria-valuetext` on each change.\n\n```javascript\nconst bar = document.querySelector('mds-progress');\n\nasync function runTask() {\n for (let i = 0; i <= 10; i++) {\n await doWork(i);\n bar.progress = i / 10;\n }\n}\n```\n\n#### Styling Customization\n\nOverride the documented `--mds-progress-*` CSS custom properties for one-off visual tweaks. Use Magma color tokens via `rgb(var(--<token>))` so dark mode keeps working.\n\n```css\n.upload-widget mds-progress {\n --mds-progress-background: rgb(var(--tone-neutral-09));\n --mds-progress-color: rgb(var(--variant-secondary-03));\n --mds-progress-thickness: 16px;\n --mds-progress-duration: 400ms;\n}\n```\n",
|
|
23193
22940
|
"3. Antipattern": "Common incorrect uses of `<mds-progress>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use a Raw `<progress>` Element\n\nReplacing `<mds-progress>` with the native element loses the Magma theme, the step-announcement system, and automatic `aria-valuenow` wiring.\n\n```html\n<!-- 🚫 INCORRECT -->\n<progress value=\"40\" max=\"100\"></progress>\n\n<!-- ✅ CORRECT -->\n<mds-progress progress=\"0.4\" aria-label=\"Avanzamento operazione\"></mds-progress>\n```\n\n#### Do Not Pass `progress` as a Percentage Integer\n\n`progress` is a fractional value between `0` and `1`, not a percentage. Passing `40` instead of `0.4` pins the bar at 100% fill and sets `aria-valuenow` to `4000`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-progress progress=\"40\"></mds-progress>\n\n<!-- ✅ CORRECT -->\n<mds-progress progress=\"0.4\" aria-label=\"Avanzamento caricamento\"></mds-progress>\n```\n\n#### Do Not Omit an Accessible Name\n\nWithout `aria-label` (or `aria-labelledby`) and without `aria-hidden=\"true\"`, the progressbar role has no text label and screen readers can only announce the numeric value with no context.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-progress progress=\"0.6\"></mds-progress>\n\n<!-- ✅ CORRECT - informative bar with a label -->\n<mds-progress progress=\"0.6\" aria-label=\"Invio email in corso\"></mds-progress>\n\n<!-- ✅ CORRECT - purely decorative, no label needed -->\n<mds-progress progress=\"0.6\" aria-hidden=\"true\"></mds-progress>\n```\n\n#### Do Not Use `direction=\"radial\"` Without a Width Constraint\n\nThe radial variant sizes itself from the host's width. Without an explicit width the ring expands to fill the container, often breaking the layout.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-progress progress=\"0.5\" direction=\"radial\"></mds-progress>\n\n<!-- ✅ CORRECT -->\n<mds-progress progress=\"0.5\" direction=\"radial\" style=\"width: 80px;\" aria-label=\"Completamento\"></mds-progress>\n```\n\n#### Do Not Use `typography` on Bar Directions\n\nThe `typography` prop controls the type scale of the centered percentage label rendered only when `direction=\"radial\"`. Setting it on `horizontal` or `vertical` bars has no visual effect and misleads readers.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-progress progress=\"0.5\" direction=\"horizontal\" typography=\"label\"></mds-progress>\n\n<!-- ✅ CORRECT -->\n<mds-progress progress=\"0.5\" direction=\"radial\" typography=\"label\" style=\"width: 64px;\" aria-label=\"Avanzamento\"></mds-progress>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Fill\n\n`::part(progress)` is the supported way to reach the fill element; `>>>` or undocumented class names are not. Prefer the `--mds-progress-*` CSS custom properties for the most common overrides.\n\n```css\n/* 🚫 INCORRECT */\nmds-progress >>> .progress {\n background: hotpink;\n}\n\n/* ✅ CORRECT - use the CSS custom property */\nmds-progress {\n --mds-progress-color: rgb(var(--variant-secondary-03));\n}\n\n/* ✅ CORRECT - use the documented part only when a property is insufficient */\nmds-progress::part(progress) {\n border-radius: 0;\n}\n```\n\n#### Do Not Set `aria-hidden=\"false\"` to Re-enable Semantics\n\n`aria-hidden=\"false\"` is a string attribute - it is truthy in HTML. To restore progressbar semantics after hiding the bar, remove the attribute entirely.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-progress progress=\"0.5\" aria-hidden=\"false\" aria-label=\"Avanzamento\"></mds-progress>\n\n<!-- ✅ CORRECT -->\n<mds-progress progress=\"0.5\" aria-label=\"Avanzamento\"></mds-progress>\n```\n"
|
|
23194
22941
|
},
|
|
23195
22942
|
"props": [
|
|
@@ -24286,30 +24033,7 @@
|
|
|
24286
24033
|
"setter": false
|
|
24287
24034
|
}
|
|
24288
24035
|
],
|
|
24289
|
-
"methods": [
|
|
24290
|
-
{
|
|
24291
|
-
"name": "updateLang",
|
|
24292
|
-
"returns": {
|
|
24293
|
-
"type": "Promise<void>",
|
|
24294
|
-
"docs": ""
|
|
24295
|
-
},
|
|
24296
|
-
"complexType": {
|
|
24297
|
-
"signature": "() => Promise<void>",
|
|
24298
|
-
"parameters": [],
|
|
24299
|
-
"references": {
|
|
24300
|
-
"Promise": {
|
|
24301
|
-
"location": "global",
|
|
24302
|
-
"id": "global::Promise"
|
|
24303
|
-
}
|
|
24304
|
-
},
|
|
24305
|
-
"return": "Promise<void>"
|
|
24306
|
-
},
|
|
24307
|
-
"signature": "updateLang() => Promise<void>",
|
|
24308
|
-
"parameters": [],
|
|
24309
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
24310
|
-
"docsTags": []
|
|
24311
|
-
}
|
|
24312
|
-
],
|
|
24036
|
+
"methods": [],
|
|
24313
24037
|
"events": [
|
|
24314
24038
|
{
|
|
24315
24039
|
"event": "mdsPushNotificationItemClose",
|
|
@@ -26261,7 +25985,7 @@
|
|
|
26261
25985
|
"usage": {
|
|
26262
25986
|
"1. Description": "The `<mds-stepper-bar-item>` web component represents a single step inside a [`<mds-stepper-bar>`](../../mds-stepper-bar) progress indicator, rendering the step's icon, optional ordinal label, descriptive text and status badge. It has no standalone meaning: it is the unit the parent stepper orchestrates to express a sequential, multi-step flow.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-stepper-bar>`; it is not used standalone or mixed with other child types in that slot.\n- **State driven by the parent**: The `done` and `current` props are not set per item by the consumer - the parent's `itemsDone` prop drives `done`/`current` on each child, so an item's visual state is a function of its position relative to the active step.\n- **Index resolution**: The item computes its own ordinal from its position among the parent's children; this index feeds the localized \"step N\" caption rendered when `step` is enabled.\n- **Three-way status badge**: When `badge` is true the item renders a status badge whose variant and localized text reflect the resolved state - `success`/done, `info`/current, or `dark`/queued.\n- **Icon swap on completion**: The displayed icon switches from `icon` to `iconChecked` once the item is done and no longer current.\n- **Selection event bubbles up**: It emits `mdsStepperBarItemDone` (detail `{ value }`), which the parent listens for to mark this item current and recompute the flow. The item is keyboard-activatable.\n- **Localization**: Step, badge and status strings are localized (el/en/es/it).\n\n#### Properties & Visual Configurations\n\nMost state props are managed by the parent rather than the consumer. The props worth configuring directly on each item are:\n\n- **`icon` / `iconChecked`**: Set `icon` for the default and current appearance; set `iconChecked` only when the completed step should show a different glyph (it defaults to `icon`).\n- **`step`**: Enable to surface the auto-numbered \"step N\" caption above the label - use it for explicitly ordered flows where the number aids orientation.\n- **`badge`**: Enable to show the queued/current/done status pill; prefer it when status legibility matters more than horizontal compactness.\n- **`value`**: The token carried in the `mdsStepperBarItemDone` event detail; set it so the parent can aggregate which steps have been completed.\n- **`typography`**: Overrides the label's typography token (defaults to `h6`); lower it for denser bars.\n",
|
|
26263
25987
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-stepper-bar-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Minimal Step Inside a Stepper Bar\n\nPlace `<mds-stepper-bar-item>` elements as direct children of [`<mds-stepper-bar>`](../../mds-stepper-bar). Each item requires `label` and `icon`. `items-done` on the parent drives the `done` and `current` state of each child automatically.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n icon=\"mi/baseline/person\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/location-on\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Distinct Icon for the Completed State\n\nSet `icon-checked` to a different slug when the done state should show a different glyph - for example a checkmark. When omitted, `icon-checked` defaults to `icon`.\n\n```html\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Showing the Ordinal Caption with `step`\n\nSet the boolean `step` attribute to surface an auto-numbered \"Step N\" caption above the label. Use this for explicitly ordered flows where the ordinal number aids orientation.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Status Badge via `badge`\n\nSet `badge` to show the localized status pill (Completato / In corso / In coda). Prefer this when status legibility matters more than horizontal compactness.\n\n```html\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Carrying a Value for Event Handling\n\nSet `value` on each item so the `mdsStepperBarItemDone` event carries a meaningful identifier. Listen to the event on the parent or a common ancestor.\n\n```html\n<mds-stepper-bar id=\"stepper\" items-done=\"1\">\n <mds-stepper-bar-item\n value=\"dati-personali\"\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n value=\"indirizzo\"\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n value=\"pagamento\"\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n\n<script>\n document.getElementById('stepper').addEventListener('mdsStepperBarChange', (e) => {\n console.log('step completati:', e.detail.value, 'step corrente:', e.detail.step);\n });\n</script>\n```\n\n#### Pairing Step Content via the `content` Slot\n\nPlace panel elements with `slot=\"content\"` inside `<mds-stepper-bar>` - one per item in order. The parent shows only the panel matching the current step.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/payment\" label=\"Pagamento\"></mds-stepper-bar-item>\n\n <div slot=\"content\">\n <p>Inserisci il tuo nome e cognome.</p>\n </div>\n <div slot=\"content\">\n <p>Inserisci il tuo indirizzo di spedizione.</p>\n </div>\n <div slot=\"content\">\n <p>Scegli il metodo di pagamento.</p>\n </div>\n</mds-stepper-bar>\n```\n\n#### Reducing Label Typography for Dense Bars\n\nLower the `typography` prop (default `h6`) when horizontal space is tight or when the label must blend with smaller surrounding text.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Styling Customization\n\nStyle items only through the documented `--mds-stepper-bar-item-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working. Target the `::part(badge)` surface only when a deep visual override of the badge wrapper is required.\n\n```css\n.checkout-flow mds-stepper-bar-item {\n --mds-stepper-bar-item-icon-background-current: rgb(var(--variant-secondary-04));\n --mds-stepper-bar-item-icon-color-current: rgb(var(--tone-neutral));\n --mds-stepper-bar-item-icon-background-done: rgb(var(--status-success-05));\n --mds-stepper-bar-item-progress-color: rgb(var(--status-success-04));\n --mds-stepper-bar-item-min-width: 160px;\n}\n```\n",
|
|
26264
|
-
"3. Antipattern": "Common incorrect uses of `<mds-stepper-bar-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use Outside `<mds-stepper-bar>`\n\n`<mds-stepper-bar-item>` is a compound child - its state (`done`, `current`, index) is resolved by the parent. Using it standalone leaves `isDone`, `isCurrent` and `index` at their defaults and produces broken visual output.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-stepper-bar-item icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n\n<!-- ✅ CORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Do Not Set `done=\"false\"` or `current=\"false\"` as Strings\n\n`done` and `current` are boolean props; any non-empty string value is truthy in HTML. To turn them off, remove the attribute or let the parent manage state via `items-done`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-stepper-bar-item done=\"false\" current=\"false\" icon=\"mi/baseline/payment\" label=\"Pagamento\"></mds-stepper-bar-item>\n\n<!-- ✅ CORRECT -->\n<mds-stepper-bar-item icon=\"mi/baseline/payment\" label=\"Pagamento\"></mds-stepper-bar-item>\n```\n\n#### Do Not Override State Manually When the Parent Manages It\n\n`done` and `current` are driven by `<mds-stepper-bar>`'s `items-done` prop. Setting them on individual items and also setting `items-done` creates conflicting state that the parent overwrites on each render cycle.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item done current icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n\n<!-- ✅ CORRECT -->\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Do Not Wrap Items in Extra HTML Elements\n\nThe parent queries `mds-stepper-bar-item` elements directly; a wrapper `<div>` or `<li>` breaks the parent-child communication, index resolution and scroll alignment.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <div>\n <mds-stepper-bar-item icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n </div>\n <div>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" label=\"Indirizzo\"></mds-stepper-bar-item>\n </div>\n</mds-stepper-bar>\n\n<!-- ✅ CORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Do Not Use Undocumented `::part()` Targets to Style the Icon or Progress\n\nThe only documented shadow part is `badge`. Targeting internals such as `::part(icon)` or `::part(progress)` couples code to the private Shadow DOM structure and will break on minor releases. Use the `--mds-stepper-bar-item-*` CSS custom properties instead.\n\n```css\n/* 🚫 INCORRECT */\nmds-stepper-bar-item::part(icon) {\n background-color: purple;\n}\nmds-stepper-bar-item::part(progress) {\n height: 6px;\n}\n\n/* ✅ CORRECT */\nmds-stepper-bar-item {\n --mds-stepper-bar-item-icon-background-current: rgb(var(--variant-primary-04));\n --mds-stepper-bar-item-progress-thickness:
|
|
25988
|
+
"3. Antipattern": "Common incorrect uses of `<mds-stepper-bar-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use Outside `<mds-stepper-bar>`\n\n`<mds-stepper-bar-item>` is a compound child - its state (`done`, `current`, index) is resolved by the parent. Using it standalone leaves `isDone`, `isCurrent` and `index` at their defaults and produces broken visual output.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-stepper-bar-item icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n\n<!-- ✅ CORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Do Not Set `done=\"false\"` or `current=\"false\"` as Strings\n\n`done` and `current` are boolean props; any non-empty string value is truthy in HTML. To turn them off, remove the attribute or let the parent manage state via `items-done`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-stepper-bar-item done=\"false\" current=\"false\" icon=\"mi/baseline/payment\" label=\"Pagamento\"></mds-stepper-bar-item>\n\n<!-- ✅ CORRECT -->\n<mds-stepper-bar-item icon=\"mi/baseline/payment\" label=\"Pagamento\"></mds-stepper-bar-item>\n```\n\n#### Do Not Override State Manually When the Parent Manages It\n\n`done` and `current` are driven by `<mds-stepper-bar>`'s `items-done` prop. Setting them on individual items and also setting `items-done` creates conflicting state that the parent overwrites on each render cycle.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item done current icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n\n<!-- ✅ CORRECT -->\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Do Not Wrap Items in Extra HTML Elements\n\nThe parent queries `mds-stepper-bar-item` elements directly; a wrapper `<div>` or `<li>` breaks the parent-child communication, index resolution and scroll alignment.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <div>\n <mds-stepper-bar-item icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n </div>\n <div>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" label=\"Indirizzo\"></mds-stepper-bar-item>\n </div>\n</mds-stepper-bar>\n\n<!-- ✅ CORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Do Not Use Undocumented `::part()` Targets to Style the Icon or Progress\n\nThe only documented shadow part is `badge`. Targeting internals such as `::part(icon)` or `::part(progress)` couples code to the private Shadow DOM structure and will break on minor releases. Use the `--mds-stepper-bar-item-*` CSS custom properties instead.\n\n```css\n/* 🚫 INCORRECT */\nmds-stepper-bar-item::part(icon) {\n background-color: purple;\n}\nmds-stepper-bar-item::part(progress) {\n height: 6px;\n}\n\n/* ✅ CORRECT */\nmds-stepper-bar-item {\n --mds-stepper-bar-item-icon-background-current: rgb(var(--variant-primary-04));\n --mds-stepper-bar-item-progress-thickness: 6px;\n}\n```\n\n#### Do Not Omit `label` or `icon`\n\nBoth are required props. An item without `label` has no accessible or visual description; an item without `icon` leaves the icon area empty and breaks the progress-line layout.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n\n<!-- ✅ CORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n"
|
|
26265
25989
|
},
|
|
26266
25990
|
"props": [
|
|
26267
25991
|
{
|
|
@@ -26569,30 +26293,7 @@
|
|
|
26569
26293
|
"setter": false
|
|
26570
26294
|
}
|
|
26571
26295
|
],
|
|
26572
|
-
"methods": [
|
|
26573
|
-
{
|
|
26574
|
-
"name": "updateLang",
|
|
26575
|
-
"returns": {
|
|
26576
|
-
"type": "Promise<void>",
|
|
26577
|
-
"docs": ""
|
|
26578
|
-
},
|
|
26579
|
-
"complexType": {
|
|
26580
|
-
"signature": "() => Promise<void>",
|
|
26581
|
-
"parameters": [],
|
|
26582
|
-
"references": {
|
|
26583
|
-
"Promise": {
|
|
26584
|
-
"location": "global",
|
|
26585
|
-
"id": "global::Promise"
|
|
26586
|
-
}
|
|
26587
|
-
},
|
|
26588
|
-
"return": "Promise<void>"
|
|
26589
|
-
},
|
|
26590
|
-
"signature": "updateLang() => Promise<void>",
|
|
26591
|
-
"parameters": [],
|
|
26592
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
26593
|
-
"docsTags": []
|
|
26594
|
-
}
|
|
26595
|
-
],
|
|
26296
|
+
"methods": [],
|
|
26596
26297
|
"events": [
|
|
26597
26298
|
{
|
|
26598
26299
|
"event": "mdsStepperBarItemDone",
|
|
@@ -26624,7 +26325,7 @@
|
|
|
26624
26325
|
"docs": "Sets the color of the text"
|
|
26625
26326
|
},
|
|
26626
26327
|
{
|
|
26627
|
-
"name": "--mds-stepper-bar-item-
|
|
26328
|
+
"name": "--mds-stepper-bar-item-duration",
|
|
26628
26329
|
"annotation": "prop",
|
|
26629
26330
|
"docs": "Sets the duration of the animation"
|
|
26630
26331
|
},
|
|
@@ -27171,8 +26872,8 @@
|
|
|
27171
26872
|
"mds-pref-consumption",
|
|
27172
26873
|
"mds-pref-contrast",
|
|
27173
26874
|
"mds-pref-language",
|
|
27174
|
-
"mds-pref-
|
|
27175
|
-
"mds-pref-theme
|
|
26875
|
+
"mds-pref-mode",
|
|
26876
|
+
"mds-pref-theme"
|
|
27176
26877
|
],
|
|
27177
26878
|
"dependencies": [],
|
|
27178
26879
|
"dependencyGraph": {
|
|
@@ -27191,10 +26892,10 @@
|
|
|
27191
26892
|
"mds-pref-language": [
|
|
27192
26893
|
"mds-tab"
|
|
27193
26894
|
],
|
|
27194
|
-
"mds-pref-
|
|
26895
|
+
"mds-pref-mode": [
|
|
27195
26896
|
"mds-tab"
|
|
27196
26897
|
],
|
|
27197
|
-
"mds-pref-theme
|
|
26898
|
+
"mds-pref-theme": [
|
|
27198
26899
|
"mds-tab"
|
|
27199
26900
|
]
|
|
27200
26901
|
}
|
|
@@ -27600,6 +27301,32 @@
|
|
|
27600
27301
|
"getter": false,
|
|
27601
27302
|
"setter": false
|
|
27602
27303
|
},
|
|
27304
|
+
{
|
|
27305
|
+
"name": "expanded",
|
|
27306
|
+
"type": "boolean | undefined",
|
|
27307
|
+
"complexType": {
|
|
27308
|
+
"original": "boolean",
|
|
27309
|
+
"resolved": "boolean | undefined",
|
|
27310
|
+
"references": {}
|
|
27311
|
+
},
|
|
27312
|
+
"mutable": false,
|
|
27313
|
+
"attr": "expanded",
|
|
27314
|
+
"reflectToAttr": false,
|
|
27315
|
+
"docs": "Specifies whether the popup the tab item opens is showing. Left unset the tab says nothing\nabout a popup, which is what a tab that opens none has to say.",
|
|
27316
|
+
"docsTags": [],
|
|
27317
|
+
"values": [
|
|
27318
|
+
{
|
|
27319
|
+
"type": "boolean"
|
|
27320
|
+
},
|
|
27321
|
+
{
|
|
27322
|
+
"type": "undefined"
|
|
27323
|
+
}
|
|
27324
|
+
],
|
|
27325
|
+
"optional": true,
|
|
27326
|
+
"required": false,
|
|
27327
|
+
"getter": false,
|
|
27328
|
+
"setter": false
|
|
27329
|
+
},
|
|
27603
27330
|
{
|
|
27604
27331
|
"name": "href",
|
|
27605
27332
|
"type": "string | undefined",
|
|
@@ -27966,8 +27693,8 @@
|
|
|
27966
27693
|
"mds-pref-consumption",
|
|
27967
27694
|
"mds-pref-contrast",
|
|
27968
27695
|
"mds-pref-language",
|
|
27969
|
-
"mds-pref-
|
|
27970
|
-
"mds-pref-theme
|
|
27696
|
+
"mds-pref-mode",
|
|
27697
|
+
"mds-pref-theme"
|
|
27971
27698
|
],
|
|
27972
27699
|
"dependencies": [
|
|
27973
27700
|
"mds-button"
|
|
@@ -27996,10 +27723,10 @@
|
|
|
27996
27723
|
"mds-pref-language": [
|
|
27997
27724
|
"mds-tab-item"
|
|
27998
27725
|
],
|
|
27999
|
-
"mds-pref-
|
|
27726
|
+
"mds-pref-mode": [
|
|
28000
27727
|
"mds-tab-item"
|
|
28001
27728
|
],
|
|
28002
|
-
"mds-pref-theme
|
|
27729
|
+
"mds-pref-theme": [
|
|
28003
27730
|
"mds-tab-item"
|
|
28004
27731
|
]
|
|
28005
27732
|
}
|
|
@@ -28643,28 +28370,6 @@
|
|
|
28643
28370
|
"text": "totalItems the total number of selectable rows"
|
|
28644
28371
|
}
|
|
28645
28372
|
]
|
|
28646
|
-
},
|
|
28647
|
-
{
|
|
28648
|
-
"name": "updateLang",
|
|
28649
|
-
"returns": {
|
|
28650
|
-
"type": "Promise<void>",
|
|
28651
|
-
"docs": ""
|
|
28652
|
-
},
|
|
28653
|
-
"complexType": {
|
|
28654
|
-
"signature": "() => Promise<void>",
|
|
28655
|
-
"parameters": [],
|
|
28656
|
-
"references": {
|
|
28657
|
-
"Promise": {
|
|
28658
|
-
"location": "global",
|
|
28659
|
-
"id": "global::Promise"
|
|
28660
|
-
}
|
|
28661
|
-
},
|
|
28662
|
-
"return": "Promise<void>"
|
|
28663
|
-
},
|
|
28664
|
-
"signature": "updateLang() => Promise<void>",
|
|
28665
|
-
"parameters": [],
|
|
28666
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
28667
|
-
"docsTags": []
|
|
28668
28373
|
}
|
|
28669
28374
|
],
|
|
28670
28375
|
"events": [],
|
|
@@ -28719,8 +28424,8 @@
|
|
|
28719
28424
|
"docsTags": [],
|
|
28720
28425
|
"usage": {
|
|
28721
28426
|
"1. Description": "The `<mds-table-header-cell>` web component is the column-header cell of a Magma data table. It is a compound child of [`<mds-table-header>`](../../mds-table-header) and plays the role of a native `<th>` (`columnheader`), rendering the column label and, when enabled, acting as the interactive sort control for its column.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct slot child of `<mds-table-header>`; it is not used standalone, and its sorting acts on the body rows within the enclosing `mds-table`.\n- **Header role and ARIA sort**: Reflects its current sort state through `aria-sort`, mirroring the `direction` prop (`none` / `ascending` / `descending`).\n- **Position-based sorting**: The cell sorts the matching `mds-table-cell` of every body row by column position; values come from each cell's `value` (falling back to trimmed text), with numeric values compared numerically and others compared alphabetically.\n- **Tri-state sort cycle**: Each activation advances the column through `none` → `ascending` → `descending` and back to `none`; the `none` state restores the original row order.\n- **Single active sort column**: Sorting a column resets every sibling header cell to `none`, so only one column drives the order at a time.\n- **Conditional rendering**: When `sortable` is set the cell renders a clickable sorter (with an up / down / unfold-more icon reflecting `direction`); otherwise it renders a plain label with no interaction.\n\n#### Properties & Visual Configurations\n\n- **`sortable`**: Opt a column into interactive sorting. Leave it unset for purely descriptive columns (label only); set it when the column's values should be reorderable by the user.\n- **`direction`**: The reflected sort state of the column (`none`, `ascending`, `descending`). It is self-managed by the click cycle, but can be set externally - for example to clear a column to `none` - and drives both the rendered sort icon and the `aria-sort` value.\n",
|
|
28722
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-table-header-cell>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound table structure documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Plain Header Cell\n\nThe simplest form: a non-sortable column header that renders a styled label. Omit `sortable` for columns whose values should not be reordered.\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=\"Ruolo\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Mario Rossi</mds-table-cell>\n <mds-table-cell>Amministratore</mds-table-cell>\n <mds-table-cell>Attivo</mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Sortable Column Header\n\nAdd the `sortable` boolean attribute to enable the tri-state click cycle (`none` -> `ascending` -> `descending` -> `none`). The component manages sorting internally - no JavaScript wiring is required.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Cognome\" sortable></mds-table-header-cell>\n <mds-table-header-cell label=\"Dipartimento\" sortable></mds-table-header-cell>\n <mds-table-header-cell label=\"Note\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Bianchi</mds-table-cell>\n <mds-table-cell>Risorse Umane</mds-table-cell>\n <mds-table-cell>-</mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell>Amendola</mds-table-cell>\n <mds-table-cell>Informatica</mds-table-cell>\n <mds-table-cell>-</mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Mixing Sortable and Non-Sortable Columns\n\nPlace `sortable` only on columns whose values are meaningfully orderable. Action columns or complex-content columns should remain non-sortable.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"ID\" sortable></mds-table-header-cell>\n <mds-table-header-cell label=\"Descrizione\" sortable></mds-table-header-cell>\n <mds-table-header-cell label=\"Importo\" sortable></mds-table-header-cell>\n <mds-table-header-cell label=\"Azioni\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell value=\"1\">1</mds-table-cell>\n <mds-table-cell>Abbonamento annuale</mds-table-cell>\n <mds-table-cell value=\"120\">120,00 EUR</mds-table-cell>\n <mds-table-cell><mds-button label=\"Modifica\" tone=\"text\" variant=\"primary\"></mds-button></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell value=\"2\">2</mds-table-cell>\n <mds-table-cell>Licenza mensile</mds-table-cell>\n <mds-table-cell value=\"15\">15,00 EUR</mds-table-cell>\n <mds-table-cell><mds-button label=\"Modifica\" tone=\"text\" variant=\"primary\"></mds-button></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Providing Numeric Values for Correct Sort Order\n\nWhen a column displays formatted text (currency, percentages) but should sort numerically, set the `value` prop on each `<mds-table-cell>` to the raw numeric string. The header cell reads `value` first and falls back to text content.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Prodotto\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Punteggio\" sortable></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Prodotto A</mds-table-cell>\n <mds-table-cell value=\"8.5\">8,5 / 10</mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell>Prodotto B</mds-table-cell>\n <mds-table-cell value=\"10\">10 / 10</mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell>Prodotto C</mds-table-cell>\n <mds-table-cell value=\"2.3\">2,3 / 10</mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Programmatically Resetting Sort Direction\n\nSet `direction=\"none\"` from outside to clear a column's active sort - for example when the user applies a server-side filter that invalidates the current order. Only the `none` value can be set externally; the component manages `ascending` / `descending` itself through click cycles.\n\n```html\n<!-- Mark the column as sorted ascending on initial render -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Data\" sortable direction=\"ascending\" id=\"col-data\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Categoria\" sortable></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <!-- rows -->\n </mds-table-body>\n</mds-table>\n```\n\n```js\n// Reset to unsorted when a new server response arrives\ndocument.querySelector('#col-data').direction = 'none';\n```\n\n#### Styling Customization\n\
|
|
28723
|
-
"3. Antipattern": "Common incorrect uses of `<mds-table-header-cell>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use Outside `mds-table-header`\n\n`<mds-table-header-cell>` is a compound child component and relies on traversing the DOM to locate its sibling cells and the `<mds-table-body>` for sorting. Using it outside `<mds-table-header>` breaks both the layout and the sort logic.\n\n```html\n<!-- 🚫 INCORRECT -->\n<div class=\"table-head\">\n <mds-table-header-cell label=\"Nome\" sortable></mds-table-header-cell>\n</div>\n\n<!-- ✅ CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\" sortable></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n\n#### Do Not Set `direction` to Drive the Sort Cycle\n\nThe `ascending` / `descending` states are managed by the internal click cycle; setting them from outside does not trigger a re-sort. Only `direction=\"none\"` is safe to set externally - use it to clear a column back to the unsorted state.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-table-header-cell label=\"Data\" sortable direction=\"ascending\"></mds-table-header-cell>\n\n<!-- ✅ CORRECT - let the user click to enter the sort cycle, or reset to none programmatically -->\n<mds-table-header-cell label=\"Data\" sortable></mds-table-header-cell>\n```\n\n```js\n// Only resetting to none is a safe external write\ndocument.querySelector('mds-table-header-cell').direction = 'none';\n```\n\n#### Do Not Use `sortable=\"false\"` to Disable Sorting\n\n`sortable` is a boolean attribute. Any non-empty string value - including `\"false\"` - is treated as `true` in HTML and Stencil. Remove the attribute entirely to produce a non-sortable header cell.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-table-header-cell label=\"Stato\" sortable=\"false\"></mds-table-header-cell>\n\n<!-- ✅ CORRECT -->\n<mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n```\n\n#### Do Not Slot Content Instead of Using the `label` Prop\n\nThe component renders its label through the `label` prop; there is no documented slot. Placing text or elements as children of the host puts them in an unsupported slot and they will not appear.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-table-header-cell sortable>\n <span>Cognome</span>\n</mds-table-header-cell>\n\n<!-- ✅ CORRECT -->\n<mds-table-header-cell label=\"Cognome\" sortable></mds-table-header-cell>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Sort Button\n\nThe sort button is an internal `<mds-button>` inside the shadow root. Use the documented `::part(action)`
|
|
28427
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-table-header-cell>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound table structure documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Plain Header Cell\n\nThe simplest form: a non-sortable column header that renders a styled label. Omit `sortable` for columns whose values should not be reordered.\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=\"Ruolo\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Mario Rossi</mds-table-cell>\n <mds-table-cell>Amministratore</mds-table-cell>\n <mds-table-cell>Attivo</mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Sortable Column Header\n\nAdd the `sortable` boolean attribute to enable the tri-state click cycle (`none` -> `ascending` -> `descending` -> `none`). The component manages sorting internally - no JavaScript wiring is required.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Cognome\" sortable></mds-table-header-cell>\n <mds-table-header-cell label=\"Dipartimento\" sortable></mds-table-header-cell>\n <mds-table-header-cell label=\"Note\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Bianchi</mds-table-cell>\n <mds-table-cell>Risorse Umane</mds-table-cell>\n <mds-table-cell>-</mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell>Amendola</mds-table-cell>\n <mds-table-cell>Informatica</mds-table-cell>\n <mds-table-cell>-</mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Mixing Sortable and Non-Sortable Columns\n\nPlace `sortable` only on columns whose values are meaningfully orderable. Action columns or complex-content columns should remain non-sortable.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"ID\" sortable></mds-table-header-cell>\n <mds-table-header-cell label=\"Descrizione\" sortable></mds-table-header-cell>\n <mds-table-header-cell label=\"Importo\" sortable></mds-table-header-cell>\n <mds-table-header-cell label=\"Azioni\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell value=\"1\">1</mds-table-cell>\n <mds-table-cell>Abbonamento annuale</mds-table-cell>\n <mds-table-cell value=\"120\">120,00 EUR</mds-table-cell>\n <mds-table-cell><mds-button label=\"Modifica\" tone=\"text\" variant=\"primary\"></mds-button></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell value=\"2\">2</mds-table-cell>\n <mds-table-cell>Licenza mensile</mds-table-cell>\n <mds-table-cell value=\"15\">15,00 EUR</mds-table-cell>\n <mds-table-cell><mds-button label=\"Modifica\" tone=\"text\" variant=\"primary\"></mds-button></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Providing Numeric Values for Correct Sort Order\n\nWhen a column displays formatted text (currency, percentages) but should sort numerically, set the `value` prop on each `<mds-table-cell>` to the raw numeric string. The header cell reads `value` first and falls back to text content.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Prodotto\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Punteggio\" sortable></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Prodotto A</mds-table-cell>\n <mds-table-cell value=\"8.5\">8,5 / 10</mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell>Prodotto B</mds-table-cell>\n <mds-table-cell value=\"10\">10 / 10</mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell>Prodotto C</mds-table-cell>\n <mds-table-cell value=\"2.3\">2,3 / 10</mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Programmatically Resetting Sort Direction\n\nSet `direction=\"none\"` from outside to clear a column's active sort - for example when the user applies a server-side filter that invalidates the current order. Only the `none` value can be set externally; the component manages `ascending` / `descending` itself through click cycles.\n\n```html\n<!-- Mark the column as sorted ascending on initial render -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Data\" sortable direction=\"ascending\" id=\"col-data\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Categoria\" sortable></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <!-- rows -->\n </mds-table-body>\n</mds-table>\n```\n\n```js\n// Reset to unsorted when a new server response arrives\ndocument.querySelector('#col-data').direction = 'none';\n```\n\n#### Styling Customization\n\nTarget the `label` or `action` shadow parts for glyph-level overrides. Set them on the host or a parent selector.\n\n```css\nmds-table-header-cell::part(label) {\n font-weight: var(--font-weight-semibold);\n}\n```\n",
|
|
28428
|
+
"3. Antipattern": "Common incorrect uses of `<mds-table-header-cell>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use Outside `mds-table-header`\n\n`<mds-table-header-cell>` is a compound child component and relies on traversing the DOM to locate its sibling cells and the `<mds-table-body>` for sorting. Using it outside `<mds-table-header>` breaks both the layout and the sort logic.\n\n```html\n<!-- 🚫 INCORRECT -->\n<div class=\"table-head\">\n <mds-table-header-cell label=\"Nome\" sortable></mds-table-header-cell>\n</div>\n\n<!-- ✅ CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\" sortable></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n\n#### Do Not Set `direction` to Drive the Sort Cycle\n\nThe `ascending` / `descending` states are managed by the internal click cycle; setting them from outside does not trigger a re-sort. Only `direction=\"none\"` is safe to set externally - use it to clear a column back to the unsorted state.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-table-header-cell label=\"Data\" sortable direction=\"ascending\"></mds-table-header-cell>\n\n<!-- ✅ CORRECT - let the user click to enter the sort cycle, or reset to none programmatically -->\n<mds-table-header-cell label=\"Data\" sortable></mds-table-header-cell>\n```\n\n```js\n// Only resetting to none is a safe external write\ndocument.querySelector('mds-table-header-cell').direction = 'none';\n```\n\n#### Do Not Use `sortable=\"false\"` to Disable Sorting\n\n`sortable` is a boolean attribute. Any non-empty string value - including `\"false\"` - is treated as `true` in HTML and Stencil. Remove the attribute entirely to produce a non-sortable header cell.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-table-header-cell label=\"Stato\" sortable=\"false\"></mds-table-header-cell>\n\n<!-- ✅ CORRECT -->\n<mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n```\n\n#### Do Not Slot Content Instead of Using the `label` Prop\n\nThe component renders its label through the `label` prop; there is no documented slot. Placing text or elements as children of the host puts them in an unsupported slot and they will not appear.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-table-header-cell sortable>\n <span>Cognome</span>\n</mds-table-header-cell>\n\n<!-- ✅ CORRECT -->\n<mds-table-header-cell label=\"Cognome\" sortable></mds-table-header-cell>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Sort Button\n\nThe sort button is an internal `<mds-button>` inside the shadow root. Use the documented `::part(action)` instead of undocumented selectors.\n\n```css\n/* 🚫 INCORRECT */\nmds-table-header-cell >>> .action {\n background-color: red;\n}\n\n/* ✅ CORRECT */\nmds-table-header-cell::part(action) {\n /* use only documented part-level overrides */\n}\n```\n\n#### Do Not Wrap the Cell in a Native `<th>`\n\n`<mds-table-header-cell>` already carries `role=\"columnheader\"` and manages `aria-sort`. Wrapping it inside a native `<th>` doubles the ARIA semantics and produces invalid table structure.\n\n```html\n<!-- 🚫 INCORRECT -->\n<thead>\n <tr>\n <th><mds-table-header-cell label=\"Nome\"></mds-table-header-cell></th>\n </tr>\n</thead>\n\n<!-- ✅ CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n </mds-table-header>\n</mds-table>\n```\n"
|
|
28724
28429
|
},
|
|
28725
28430
|
"props": [
|
|
28726
28431
|
{
|
|
@@ -28824,13 +28529,7 @@
|
|
|
28824
28529
|
"methods": [],
|
|
28825
28530
|
"events": [],
|
|
28826
28531
|
"listeners": [],
|
|
28827
|
-
"styles": [
|
|
28828
|
-
{
|
|
28829
|
-
"name": "--mds-table-header-cell-padding",
|
|
28830
|
-
"annotation": "prop",
|
|
28831
|
-
"docs": "The padding of the table cell"
|
|
28832
|
-
}
|
|
28833
|
-
],
|
|
28532
|
+
"styles": [],
|
|
28834
28533
|
"slots": [],
|
|
28835
28534
|
"parts": [
|
|
28836
28535
|
{
|
|
@@ -29050,30 +28749,7 @@
|
|
|
29050
28749
|
"setter": false
|
|
29051
28750
|
}
|
|
29052
28751
|
],
|
|
29053
|
-
"methods": [
|
|
29054
|
-
{
|
|
29055
|
-
"name": "updateLang",
|
|
29056
|
-
"returns": {
|
|
29057
|
-
"type": "Promise<void>",
|
|
29058
|
-
"docs": ""
|
|
29059
|
-
},
|
|
29060
|
-
"complexType": {
|
|
29061
|
-
"signature": "() => Promise<void>",
|
|
29062
|
-
"parameters": [],
|
|
29063
|
-
"references": {
|
|
29064
|
-
"Promise": {
|
|
29065
|
-
"location": "global",
|
|
29066
|
-
"id": "global::Promise"
|
|
29067
|
-
}
|
|
29068
|
-
},
|
|
29069
|
-
"return": "Promise<void>"
|
|
29070
|
-
},
|
|
29071
|
-
"signature": "updateLang() => Promise<void>",
|
|
29072
|
-
"parameters": [],
|
|
29073
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
29074
|
-
"docsTags": []
|
|
29075
|
-
}
|
|
29076
|
-
],
|
|
28752
|
+
"methods": [],
|
|
29077
28753
|
"events": [],
|
|
29078
28754
|
"listeners": [],
|
|
29079
28755
|
"styles": [
|
|
@@ -29166,7 +28842,7 @@
|
|
|
29166
28842
|
},
|
|
29167
28843
|
"mutable": false,
|
|
29168
28844
|
"attr": "animation",
|
|
29169
|
-
"reflectToAttr":
|
|
28845
|
+
"reflectToAttr": true,
|
|
29170
28846
|
"docs": "Specifies if the text is animated when it is rendered",
|
|
29171
28847
|
"docsTags": [
|
|
29172
28848
|
{
|
|
@@ -29696,8 +29372,8 @@
|
|
|
29696
29372
|
"mds-pref-consumption",
|
|
29697
29373
|
"mds-pref-contrast",
|
|
29698
29374
|
"mds-pref-language",
|
|
29375
|
+
"mds-pref-mode",
|
|
29699
29376
|
"mds-pref-theme",
|
|
29700
|
-
"mds-pref-theme-variant",
|
|
29701
29377
|
"mds-price-table-features",
|
|
29702
29378
|
"mds-price-table-features-cell",
|
|
29703
29379
|
"mds-price-table-list-item",
|
|
@@ -29815,10 +29491,10 @@
|
|
|
29815
29491
|
"mds-pref-language": [
|
|
29816
29492
|
"mds-text"
|
|
29817
29493
|
],
|
|
29818
|
-
"mds-pref-
|
|
29494
|
+
"mds-pref-mode": [
|
|
29819
29495
|
"mds-text"
|
|
29820
29496
|
],
|
|
29821
|
-
"mds-pref-theme
|
|
29497
|
+
"mds-pref-theme": [
|
|
29822
29498
|
"mds-text"
|
|
29823
29499
|
],
|
|
29824
29500
|
"mds-price-table-features": [
|
|
@@ -29889,8 +29565,8 @@
|
|
|
29889
29565
|
}
|
|
29890
29566
|
],
|
|
29891
29567
|
"usage": {
|
|
29892
|
-
"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- **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- **Close event**: After the outro animation completes, the component emits `mdsToastClose` - consumers should listen for this to remove the toast from the DOM or update queue state.\n- **Reactive timer**: Changing `visible` or `duration` at runtime restarts the timer, so toggling visibility re-arms the countdown rather than leaving a stale timer.\n- **Conditional regions**: The text region renders only when the host has inner content, and the action region
|
|
29893
|
-
"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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.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 a saturated filled background; `weak` uses a lighter tint 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 inherits from `--mds-toast-icon-color` which 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
|
|
29568
|
+
"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- **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- **Close event**: After the outro animation completes, the component emits `mdsToastClose` - consumers should listen for this to remove the toast from the DOM or update queue state.\n- **Reactive timer**: Changing `visible` or `duration` at runtime restarts the timer, so toggling visibility re-arms the countdown rather than leaving a stale timer.\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 [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); `<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\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",
|
|
29569
|
+
"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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.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 a saturated filled background; `weak` uses a lighter tint 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 inherits from `--mds-toast-icon-color` which 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.\n\n```html\n<mds-toast visible variant=\"warning\" duration=\"0\">\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#### 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. 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', () => {\n // rimuovi il toast dalla coda o aggiorna lo stato dell'applicazione\n toastQueue.shift();\n});\n```\n\n#### Styling Customization\n\nStyle the toast only through its documented `--mds-toast-*` CSS custom properties. Set them on the host element or a parent selector; use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.app-notifications mds-toast {\n --mds-toast-background: rgb(var(--tone-neutral-01));\n --mds-toast-color: rgb(var(--tone-neutral-10));\n --mds-toast-icon-color: rgb(var(--variant-primary-05));\n --mds-toast-width: 480px;\n --mds-toast-shadow: var(--shadow-xl);\n}\n```\n",
|
|
29894
29570
|
"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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - 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 break the layout and may be stripped. 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 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\"` is truthy in HTML. Remove the attribute entirely (or set the prop to `undefined`) to hide the toast.\n\n```html\n<!-- 🚫 INCORRECT - the toast remains 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 the default light palette. Stick to the six documented status variants.\n\n```html\n<!-- 🚫 INCORRECT - no color override; looks identical to default -->\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 `--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 documented custom properties */\nmds-toast {\n --mds-toast-background: rgb(var(--tone-neutral-01));\n --mds-toast-width: 360px;\n}\n```\n"
|
|
29895
29571
|
},
|
|
29896
29572
|
"props": [
|
|
@@ -31087,11 +30763,6 @@
|
|
|
31087
30763
|
"annotation": "prop",
|
|
31088
30764
|
"docs": "Sets the text color of the folder icon when the item is collapsed."
|
|
31089
30765
|
},
|
|
31090
|
-
{
|
|
31091
|
-
"name": "--mds-tree-toggle-icon-folder-expanded-background",
|
|
31092
|
-
"annotation": "prop",
|
|
31093
|
-
"docs": "Sets the background-color of the folder icon when the item is expanded."
|
|
31094
|
-
},
|
|
31095
30766
|
{
|
|
31096
30767
|
"name": "--mds-tree-toggle-icon-folder-expanded-color",
|
|
31097
30768
|
"annotation": "prop",
|
|
@@ -31542,28 +31213,6 @@
|
|
|
31542
31213
|
"parameters": [],
|
|
31543
31214
|
"docs": "`internal` Re-resolves the effective actions; called by mds-tree when its own\nactions changes so items that inherit it stay in sync.",
|
|
31544
31215
|
"docsTags": []
|
|
31545
|
-
},
|
|
31546
|
-
{
|
|
31547
|
-
"name": "updateLang",
|
|
31548
|
-
"returns": {
|
|
31549
|
-
"type": "Promise<void>",
|
|
31550
|
-
"docs": ""
|
|
31551
|
-
},
|
|
31552
|
-
"complexType": {
|
|
31553
|
-
"signature": "() => Promise<void>",
|
|
31554
|
-
"parameters": [],
|
|
31555
|
-
"references": {
|
|
31556
|
-
"Promise": {
|
|
31557
|
-
"location": "global",
|
|
31558
|
-
"id": "global::Promise"
|
|
31559
|
-
}
|
|
31560
|
-
},
|
|
31561
|
-
"return": "Promise<void>"
|
|
31562
|
-
},
|
|
31563
|
-
"signature": "updateLang() => Promise<void>",
|
|
31564
|
-
"parameters": [],
|
|
31565
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
31566
|
-
"docsTags": []
|
|
31567
31216
|
}
|
|
31568
31217
|
],
|
|
31569
31218
|
"events": [
|
|
@@ -31932,30 +31581,7 @@
|
|
|
31932
31581
|
"setter": false
|
|
31933
31582
|
}
|
|
31934
31583
|
],
|
|
31935
|
-
"methods": [
|
|
31936
|
-
{
|
|
31937
|
-
"name": "updateLang",
|
|
31938
|
-
"returns": {
|
|
31939
|
-
"type": "Promise<void>",
|
|
31940
|
-
"docs": ""
|
|
31941
|
-
},
|
|
31942
|
-
"complexType": {
|
|
31943
|
-
"signature": "() => Promise<void>",
|
|
31944
|
-
"parameters": [],
|
|
31945
|
-
"references": {
|
|
31946
|
-
"Promise": {
|
|
31947
|
-
"location": "global",
|
|
31948
|
-
"id": "global::Promise"
|
|
31949
|
-
}
|
|
31950
|
-
},
|
|
31951
|
-
"return": "Promise<void>"
|
|
31952
|
-
},
|
|
31953
|
-
"signature": "updateLang() => Promise<void>",
|
|
31954
|
-
"parameters": [],
|
|
31955
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
31956
|
-
"docsTags": []
|
|
31957
|
-
}
|
|
31958
|
-
],
|
|
31584
|
+
"methods": [],
|
|
31959
31585
|
"events": [
|
|
31960
31586
|
{
|
|
31961
31587
|
"event": "mdsUrlViewClose",
|
|
@@ -32116,30 +31742,7 @@
|
|
|
32116
31742
|
"setter": false
|
|
32117
31743
|
}
|
|
32118
31744
|
],
|
|
32119
|
-
"methods": [
|
|
32120
|
-
{
|
|
32121
|
-
"name": "updateLang",
|
|
32122
|
-
"returns": {
|
|
32123
|
-
"type": "Promise<void>",
|
|
32124
|
-
"docs": ""
|
|
32125
|
-
},
|
|
32126
|
-
"complexType": {
|
|
32127
|
-
"signature": "() => Promise<void>",
|
|
32128
|
-
"parameters": [],
|
|
32129
|
-
"references": {
|
|
32130
|
-
"Promise": {
|
|
32131
|
-
"location": "global",
|
|
32132
|
-
"id": "global::Promise"
|
|
32133
|
-
}
|
|
32134
|
-
},
|
|
32135
|
-
"return": "Promise<void>"
|
|
32136
|
-
},
|
|
32137
|
-
"signature": "updateLang() => Promise<void>",
|
|
32138
|
-
"parameters": [],
|
|
32139
|
-
"docs": "Updates the component's texts to the locale currently set on the host element.",
|
|
32140
|
-
"docsTags": []
|
|
32141
|
-
}
|
|
32142
|
-
],
|
|
31745
|
+
"methods": [],
|
|
32143
31746
|
"events": [],
|
|
32144
31747
|
"listeners": [],
|
|
32145
31748
|
"styles": [
|
|
@@ -32209,8 +31812,8 @@
|
|
|
32209
31812
|
}
|
|
32210
31813
|
],
|
|
32211
31814
|
"usage": {
|
|
32212
|
-
"1. Description": "The `<mds-video-wall>` web component is the Magma Design System's full-bleed background video surface, used to render an autoplaying, looping ambient video behind foreground content. It wraps the native `<video>` element, adding an optional grain/noise overlay and a dedicated content layer for captions or call-to-action overlays.\n\n#### Semantic Behavior\n\n- **Ambient by default**: `autoplay`, `loop` and `muted` are all `true` out of the box, producing a self-contained background loop with no controls and no audio - the configuration browsers require for autoplay to be honored.\n- **Decorative video**: The footage is treated as presentation only; meaningful information must live in the `content` slot, not in the video itself.\n- **Noise overlay**: When `noise` is anything other than `'none'`, a decorative grain layer is rendered above the video; with `noise=\"none\"` the layer is omitted entirely.\n- **Conditional content layer**: The `content` overlay wrapper is only
|
|
32213
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-video-wall>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md) and the catalogue in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md).\n\n#### Minimal Ambient Background\n\nThe simplest and most common use: a full-bleed autoplaying video loop with no extra configuration needed, because `autoplay`, `loop`, and `muted` are all `true` by default.\n\n```html\n<mds-video-wall src=\"/assets/video/ambient.mp4\"></mds-video-wall>\n```\n\n#### Poster Image for Initial Frame\n\nSupply a `poster` image so users see a meaningful still frame before the video loads, or on devices where autoplay is suppressed by the browser.\n\n```html\n<mds-video-wall\n src=\"/assets/video/ambient.mp4\"\n poster=\"/assets/video/ambient-preview.webp\"\n></mds-video-wall>\n```\n\n#### Noise Overlay for Texture\n\nAdd a grain overlay with `noise` to give the video a cinematic or retro feel. Choose the texture that fits the intended mood: `classic`, `sharp`, `soft`, or `tv`.\n\n```html\n<!-- Subtle classic grain -->\n<mds-video-wall src=\"/assets/video/ambient.mp4\" noise=\"classic\"></mds-video-wall>\n\n<!-- High-contrast TV static -->\n<mds-video-wall src=\"/assets/video/ambient.mp4\" noise=\"tv\"></mds-video-wall>\n```\n\n#### Foreground Content Overlay via the `content` Slot\n\nPlace any text, HTML elements, or Magma components in the `content` slot to render them centered above the video. The overlay wrapper is
|
|
31815
|
+
"1. Description": "The `<mds-video-wall>` web component is the Magma Design System's full-bleed background video surface, used to render an autoplaying, looping ambient video behind foreground content. It wraps the native `<video>` element, adding an optional grain/noise overlay and a dedicated content layer for captions or call-to-action overlays.\n\n#### Semantic Behavior\n\n- **Ambient by default**: `autoplay`, `loop` and `muted` are all `true` out of the box, producing a self-contained background loop with no controls and no audio - the configuration browsers require for autoplay to be honored.\n- **Decorative video**: The footage is treated as presentation only; meaningful information must live in the `content` slot, not in the video itself.\n- **Noise overlay**: When `noise` is anything other than `'none'`, a decorative grain layer is rendered above the video; with `noise=\"none\"` the layer is omitted entirely.\n- **Conditional content layer**: The `content` overlay wrapper is shown only while a `slot=\"content\"` child is present, also when it is added after the first render, so an empty overlay never affects layout.\n- **Default slot is fallback text**: The default (unnamed) slot is projected inside the `<video>` element and is intended for the browser-support fallback message shown when video playback is unavailable.\n- **Preload is conditional**: `preload` only takes effect when autoplay is disabled; the browser ignores it while `autoplay` is active.\n\n#### Properties & Visual Configurations\n\nThis component does not use the shared `variant` / `tone` ladders; its props map closely to the underlying native `<video>` attributes plus the Magma-specific overlay.\n\n#### Other behavioral props\n\n- **`noise`** selects the texture/strength of the grain overlay (`'classic'`, `'sharp'`, `'soft'`, `'tv'`); choose the style that matches the intended mood, or `'none'` to disable the effect.\n- **`poster`** is the still image shown before the footage is ready - pick a frame that reads well on its own, since it is the first thing users see.\n- **`preload`** hints how aggressively the file is fetched on page load; relevant only when autoplay is off.\n- **`src`** is the URL of the video file driving the wall.\n",
|
|
31816
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-video-wall>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md) and the catalogue in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md).\n\n#### Minimal Ambient Background\n\nThe simplest and most common use: a full-bleed autoplaying video loop with no extra configuration needed, because `autoplay`, `loop`, and `muted` are all `true` by default.\n\n```html\n<mds-video-wall src=\"/assets/video/ambient.mp4\"></mds-video-wall>\n```\n\n#### Poster Image for Initial Frame\n\nSupply a `poster` image so users see a meaningful still frame before the video loads, or on devices where autoplay is suppressed by the browser.\n\n```html\n<mds-video-wall\n src=\"/assets/video/ambient.mp4\"\n poster=\"/assets/video/ambient-preview.webp\"\n></mds-video-wall>\n```\n\n#### Noise Overlay for Texture\n\nAdd a grain overlay with `noise` to give the video a cinematic or retro feel. Choose the texture that fits the intended mood: `classic`, `sharp`, `soft`, or `tv`.\n\n```html\n<!-- Subtle classic grain -->\n<mds-video-wall src=\"/assets/video/ambient.mp4\" noise=\"classic\"></mds-video-wall>\n\n<!-- High-contrast TV static -->\n<mds-video-wall src=\"/assets/video/ambient.mp4\" noise=\"tv\"></mds-video-wall>\n```\n\n#### Foreground Content Overlay via the `content` Slot\n\nPlace any text, HTML elements, or Magma components in the `content` slot to render them centered above the video. The overlay wrapper is shown only while this slot is populated, also when the content is added after the first render, so an empty overlay never affects layout.\n\n```html\n<mds-video-wall src=\"/assets/video/ambient.mp4\" noise=\"soft\">\n <div slot=\"content\" class=\"text-tone-neutral text-center\">\n <mds-text typography=\"h1\">Benvenuto in Magma</mds-text>\n <mds-button label=\"Scopri di piu\" variant=\"primary\" tone=\"strong\"></mds-button>\n </div>\n</mds-video-wall>\n```\n\n#### Browser Fallback via the Default Slot\n\nThe default (unnamed) slot is projected inside the native `<video>` element. Use it for the message displayed when the browser does not support video playback.\n\n```html\n<mds-video-wall src=\"/assets/video/ambient.mp4\">\n Il tuo browser non supporta la riproduzione video. Aggiorna il browser per continuare.\n</mds-video-wall>\n```\n\n#### Disabling Autoplay with Controlled Preload\n\nWhen the video should not play automatically - for example on a media showcase page - set `autoplay` and `loop` to `false` via a framework binding or a JS property assignment, and use `preload` to control how eagerly the file is fetched. Note: `preload` is ignored by the browser while `autoplay` is active.\n\n```html\n<!--\n Framework binding example (Angular / Lit / React attribute binding).\n Do NOT write autoplay=\"false\" in plain HTML - see 3. Antipattern.md.\n-->\n<mds-video-wall\n src=\"/assets/video/showcase.mp4\"\n poster=\"/assets/video/showcase-preview.webp\"\n preload=\"metadata\"\n></mds-video-wall>\n```\n\n```javascript\n// Disable autoplay and loop via JS property when not using a framework\nconst wall = document.querySelector('mds-video-wall');\nwall.autoplay = false;\nwall.loop = false;\n```\n\n#### CSS Customization via Documented Properties\n\nStyle the noise overlay and video fit only through the documented `--mds-video-wall-*` CSS custom properties. Set them on the host element or a parent selector, using Magma color tokens for palette-aware values.\n\n```css\n/* Warm amber noise tint, contained fit for a non-16:9 source */\n.hero-section mds-video-wall {\n --mds-video-wall-noise-background-color: rgb(var(--status-warning-03) / 0.6);\n --mds-video-wall-noise-background-size: 4px;\n --mds-video-wall-video-fit: contain;\n}\n```\n",
|
|
32214
31817
|
"3. Antipattern": "Common incorrect uses of `<mds-video-wall>`. 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 [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use `autoplay=\"false\"` or `loop=\"false\"` to Disable Boolean Props\n\nSetting a boolean attribute to the string `\"false\"` does not disable it - any non-empty string is truthy in HTML. Remove the attribute, set the JS property to `false`, or use a framework binding to turn these off.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-video-wall src=\"/assets/video/ambient.mp4\" autoplay=\"false\" loop=\"false\"></mds-video-wall>\n\n<!-- ✅ CORRECT (via JS property) -->\n<mds-video-wall src=\"/assets/video/ambient.mp4\"></mds-video-wall>\n<script>\n const wall = document.querySelector('mds-video-wall');\n wall.autoplay = false;\n wall.loop = false;\n</script>\n```\n\n#### Do Not Put Meaningful Content in the Default Slot\n\nThe default slot is projected inside the native `<video>` element and is shown only by browsers that cannot play video. Captions, headlines, CTAs, and any real UI must go in the `content` slot instead.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-video-wall src=\"/assets/video/ambient.mp4\">\n <mds-text typography=\"h1\">Benvenuto</mds-text>\n</mds-video-wall>\n\n<!-- ✅ CORRECT -->\n<mds-video-wall src=\"/assets/video/ambient.mp4\">\n Il tuo browser non supporta la riproduzione video.\n <div slot=\"content\">\n <mds-text typography=\"h1\">Benvenuto</mds-text>\n </div>\n</mds-video-wall>\n```\n\n#### Do Not Wrap `<mds-video-wall>` in a Raw `<video>` Element\n\n`<mds-video-wall>` already wraps a `<video>` internally. Nesting it inside another `<video>` is invalid HTML, produces no visible output, and makes the fallback slot unreachable.\n\n```html\n<!-- 🚫 INCORRECT -->\n<video src=\"/assets/video/ambient.mp4\" autoplay muted loop>\n <mds-video-wall src=\"/assets/video/ambient.mp4\"></mds-video-wall>\n</video>\n\n<!-- ✅ CORRECT -->\n<mds-video-wall src=\"/assets/video/ambient.mp4\"></mds-video-wall>\n```\n\n#### Do Not Override Shadow DOM Internals Directly\n\nThe noise overlay is inside the Shadow DOM. Reach it only through the documented `--mds-video-wall-noise-background-color` custom property; do not pierce the shadow with `>>>` or undocumented selectors.\n\n```css\n/* 🚫 INCORRECT */\nmds-video-wall >>> .noise {\n background-color: rgba(255, 0, 0, 0.5);\n}\n\n/* ✅ CORRECT */\nmds-video-wall {\n --mds-video-wall-noise-background-color: rgb(var(--status-error-03) / 0.5);\n}\n```\n\n#### Do Not Rely on `preload` While `autoplay` Is Active\n\nThe browser ignores the `preload` hint entirely when `autoplay` is set (which is the default). Only set `preload` after disabling `autoplay` via a JS property or framework binding.\n\n```html\n<!-- 🚫 INCORRECT (preload is silently ignored because autoplay is true by default) -->\n<mds-video-wall\n src=\"/assets/video/ambient.mp4\"\n preload=\"metadata\"\n></mds-video-wall>\n\n<!-- ✅ CORRECT: disable autoplay first, then preload is honoured by the browser -->\n<mds-video-wall\n src=\"/assets/video/showcase.mp4\"\n poster=\"/assets/video/showcase-preview.webp\"\n preload=\"metadata\"\n>\n <!-- set wall.autoplay = false via JS or framework binding -->\n</mds-video-wall>\n```\n"
|
|
32215
31818
|
},
|
|
32216
31819
|
"props": [
|
|
@@ -32473,7 +32076,7 @@
|
|
|
32473
32076
|
"docs": "The background-size used for the noise texture."
|
|
32474
32077
|
},
|
|
32475
32078
|
{
|
|
32476
|
-
"name": "--mds-video-wall-noise-
|
|
32079
|
+
"name": "--mds-video-wall-noise-filter",
|
|
32477
32080
|
"annotation": "prop",
|
|
32478
32081
|
"docs": "The CSS filter applied to the noise layer (e.g., blur, brightness)."
|
|
32479
32082
|
},
|
|
@@ -32970,7 +32573,7 @@
|
|
|
32970
32573
|
"path": "src/components/mds-keyboard/meta/type.ts"
|
|
32971
32574
|
},
|
|
32972
32575
|
"src/type/keyboard.ts::KeyboardKeyName": {
|
|
32973
|
-
"declaration": "\"option\" | \"a\" | \"1\" | \"2\" | \"b\" | \"i\" | \"p\" | \"q\" | \"s\" | \"u\" | \"end\" | \"0\" | \"3\" | \"4\" | \"5\" | \"6\" | \"7\" | \"
|
|
32576
|
+
"declaration": "\"option\" | \"a\" | \"1\" | \"2\" | \"b\" | \"i\" | \"p\" | \"q\" | \"s\" | \"u\" | \"end\" | \"0\" | \"3\" | \"4\" | \"5\" | \"6\" | \"7\" | \"shift\" | \"g\" | \"8\" | \"9\" | \"alt\" | \"altleft\" | \"altright\" | \"arrowdown\" | \"arrowleft\" | \"arrowright\" | \"arrowup\" | \"backspace\" | \"c\" | \"capslock\" | \"command\" | \"commandleft\" | \"commandright\" | \"control\" | \"controlleft\" | \"controlright\" | \"d\" | \"delete\" | \"e\" | \"enter\" | \"escape\" | \"f\" | \"f1\" | \"f10\" | \"f11\" | \"f12\" | \"f2\" | \"f3\" | \"f4\" | \"f5\" | \"f6\" | \"f7\" | \"f8\" | \"f9\" | \"h\" | \"home\" | \"j\" | \"k\" | \"l\" | \"m\" | \"n\" | \"o\" | \"optionleft\" | \"optionright\" | \"pagedown\" | \"pageup\" | \"r\" | \"shiftleft\" | \"shiftright\" | \"space\" | \"t\" | \"tab\" | \"v\" | \"w\" | \"windows\" | \"windowsleft\" | \"windowsright\" | \"x\" | \"y\" | \"z\"",
|
|
32974
32577
|
"docstring": "",
|
|
32975
32578
|
"path": "src/type/keyboard.ts"
|
|
32976
32579
|
},
|
|
@@ -32984,6 +32587,11 @@
|
|
|
32984
32587
|
"docstring": "",
|
|
32985
32588
|
"path": "src/components/mds-mention/meta/type.ts"
|
|
32986
32589
|
},
|
|
32590
|
+
"src/components/mds-mention/meta/interface.ts::MdsMentionEvent": {
|
|
32591
|
+
"declaration": "interface MdsMentionEvent {\n event: Event;\n element: HTMLMdsMentionElement;\n}",
|
|
32592
|
+
"docstring": "",
|
|
32593
|
+
"path": "src/components/mds-mention/meta/interface.ts"
|
|
32594
|
+
},
|
|
32987
32595
|
"src/components/mds-modal/meta/types.ts::ModalPositionType": {
|
|
32988
32596
|
"declaration": "export type ModalPositionType =\n | 'bottom'\n | 'bottom-left'\n | 'bottom-right'\n | 'center'\n | 'left'\n | 'right'\n | 'top'\n | 'top-left'\n | 'top-right';",
|
|
32989
32597
|
"docstring": "",
|
|
@@ -33054,7 +32662,7 @@
|
|
|
33054
32662
|
"docstring": "",
|
|
33055
32663
|
"path": "src/event-detail/language.ts"
|
|
33056
32664
|
},
|
|
33057
|
-
"src/type/preference.ts::
|
|
32665
|
+
"src/type/preference.ts::PreferenceModeType": {
|
|
33058
32666
|
"declaration": "\"dark\" | \"light\" | \"system\"",
|
|
33059
32667
|
"docstring": "",
|
|
33060
32668
|
"path": "src/type/preference.ts"
|
|
@@ -33069,10 +32677,15 @@
|
|
|
33069
32677
|
"docstring": "",
|
|
33070
32678
|
"path": "src/type/preference.ts"
|
|
33071
32679
|
},
|
|
33072
|
-
"src/
|
|
33073
|
-
"declaration": "
|
|
32680
|
+
"src/type/preference.ts::PreferenceCornerShapeChoiceType": {
|
|
32681
|
+
"declaration": "\"default\" | \"bevel\" | \"notch\" | \"round\" | \"scoop\" | \"square\" | \"squircle\"",
|
|
32682
|
+
"docstring": "",
|
|
32683
|
+
"path": "src/type/preference.ts"
|
|
32684
|
+
},
|
|
32685
|
+
"src/event-detail/theme.ts::MdsPrefThemeEventDetail": {
|
|
32686
|
+
"declaration": "export interface MdsPrefThemeEventDetail {\n name?: string;\n scheme?: PreferenceThemeSchemeType;\n}",
|
|
33074
32687
|
"docstring": "",
|
|
33075
|
-
"path": "src/event-detail/theme
|
|
32688
|
+
"path": "src/event-detail/theme.ts"
|
|
33076
32689
|
},
|
|
33077
32690
|
"src/components/mds-price-table-features-cell/meta/types.ts::PriceTableFeaturesCellType": {
|
|
33078
32691
|
"declaration": "export type PriceTableFeaturesCellType = 'custom' | 'label' | 'supported' | 'text' | 'unsupported';",
|
|
@@ -33130,7 +32743,7 @@
|
|
|
33130
32743
|
"path": "src/type/tone.ts"
|
|
33131
32744
|
},
|
|
33132
32745
|
"src/components.d.ts::ModalOverflowType": {
|
|
33133
|
-
"declaration": "
|
|
32746
|
+
"declaration": "export type ModalOverflowType = 'auto' | 'manual';",
|
|
33134
32747
|
"docstring": "",
|
|
33135
32748
|
"path": "src/components.d.ts"
|
|
33136
32749
|
},
|