@maggioli-design-system/magma 2.2.0 → 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +25 -10
- package/CHANGELOG.md +475 -0
- package/README.md +5 -2
- package/agents/assets.md +231 -28
- package/agents/color.md +5 -3
- package/agents/components.md +3 -3
- package/agents/install.md +8 -4
- package/agents/reporting.md +11 -2
- package/agents/theming.md +15 -0
- package/dist/cjs/_commonjsHelpers-CFO10eej.js +7 -0
- package/dist/cjs/{floating-controller-uOCBLTk2.js → floating-controller-D7Ekjocg.js} +18 -4
- package/dist/cjs/{floating-ui.dom-DflSHZIo.js → floating-ui.dom-EMHL7uyZ.js} +146 -94
- package/dist/cjs/icon-MMHcqbgv.js +20 -0
- package/dist/cjs/index-UmmmCMIG.js +40 -40
- package/dist/cjs/loader.cjs.js +1 -1
- package/dist/cjs/magma-components.cjs.js +1 -1
- package/dist/cjs/mds-accordion-item.cjs.entry.js +1 -1
- package/dist/cjs/mds-accordion-timer-item.cjs.entry.js +1 -1
- package/dist/cjs/mds-accordion-timer.cjs.entry.js +1 -1
- package/dist/cjs/mds-accordion.cjs.entry.js +1 -1
- package/dist/cjs/mds-avatar-stack-item.cjs.entry.js +1 -1
- package/dist/cjs/mds-avatar-stack.cjs.entry.js +1 -1
- package/dist/cjs/mds-avatar.cjs.entry.js +2 -2
- package/dist/cjs/mds-badge.cjs.entry.js +1 -1
- package/dist/cjs/mds-banner_3.cjs.entry.js +6 -6
- package/dist/cjs/mds-bibliography.cjs.entry.js +1 -1
- package/dist/cjs/mds-breadcrumb-item.cjs.entry.js +1 -1
- package/dist/cjs/mds-breadcrumb.cjs.entry.js +1 -1
- package/dist/cjs/mds-button-dropdown.cjs.entry.js +30 -2
- package/dist/cjs/mds-button-group.cjs.entry.js +1 -1
- package/dist/cjs/mds-button_3.cjs.entry.js +55 -40
- package/dist/cjs/mds-calendar_2.cjs.entry.js +60 -7
- package/dist/cjs/mds-card-content.cjs.entry.js +1 -1
- package/dist/cjs/mds-card-footer.cjs.entry.js +1 -1
- package/dist/cjs/mds-card-header.cjs.entry.js +1 -1
- package/dist/cjs/mds-card-media.cjs.entry.js +2 -2
- package/dist/cjs/mds-card.cjs.entry.js +2 -2
- package/dist/cjs/mds-details.cjs.entry.js +2 -2
- package/dist/cjs/mds-dropdown.cjs.entry.js +5 -5
- package/dist/cjs/mds-emoji.cjs.entry.js +2 -2
- package/dist/cjs/mds-entity.cjs.entry.js +2 -2
- package/dist/cjs/mds-file-preview.cjs.entry.js +3 -3
- package/dist/cjs/mds-file.cjs.entry.js +29 -7520
- package/dist/cjs/mds-filter-item.cjs.entry.js +89 -3
- package/dist/cjs/mds-filter.cjs.entry.js +113 -19
- package/dist/cjs/mds-header-bar.cjs.entry.js +29 -2
- package/dist/cjs/mds-header.cjs.entry.js +2 -2
- package/dist/cjs/mds-horizontal-scroll.cjs.entry.js +38 -2
- package/dist/cjs/mds-hr.cjs.entry.js +2 -2
- package/dist/cjs/mds-img.cjs.entry.js +1 -1
- package/dist/cjs/mds-input-date-range-preselection.cjs.entry.js +2 -2
- package/dist/cjs/mds-input-date-range.cjs.entry.js +16 -2
- package/dist/cjs/mds-input-date.cjs.entry.js +36 -4
- package/dist/cjs/mds-input-field.cjs.entry.js +2 -2
- package/dist/cjs/mds-input-otp.cjs.entry.js +1 -1
- package/dist/cjs/mds-input-range.cjs.entry.js +2 -2
- package/dist/cjs/mds-input-select.cjs.entry.js +32 -5
- package/dist/cjs/mds-input-switch_2.cjs.entry.js +21 -8
- package/dist/cjs/mds-input-tip_2.cjs.entry.js +5 -5
- package/dist/cjs/mds-input-upload.cjs.entry.js +6 -6
- package/dist/cjs/mds-input.cjs.entry.js +12 -3
- package/dist/cjs/mds-keyboard-key.cjs.entry.js +2 -2
- package/dist/cjs/mds-keyboard.cjs.entry.js +2 -2
- package/dist/cjs/mds-kpi-item.cjs.entry.js +2 -2
- package/dist/cjs/mds-kpi.cjs.entry.js +1 -1
- package/dist/cjs/mds-label.cjs.entry.js +1 -1
- package/dist/cjs/mds-list-item.cjs.entry.js +2 -3
- package/dist/cjs/mds-list.cjs.entry.js +1 -1
- package/dist/cjs/mds-mention.cjs.entry.js +2 -2
- package/dist/cjs/mds-modal.cjs.entry.js +32 -5
- package/dist/cjs/mds-note.cjs.entry.js +2 -2
- package/dist/cjs/mds-notification.cjs.entry.js +3 -3
- package/dist/cjs/mds-paginator-item.cjs.entry.js +2 -2
- package/dist/cjs/mds-paginator.cjs.entry.js +2 -2
- package/dist/cjs/mds-policy-ai.cjs.entry.js +2 -2
- package/dist/cjs/mds-pref-animation.cjs.entry.js +2 -2
- package/dist/cjs/mds-pref-consumption.cjs.entry.js +2 -2
- package/dist/cjs/mds-pref-contrast.cjs.entry.js +2 -2
- package/dist/cjs/mds-pref-language-item.cjs.entry.js +1 -1
- package/dist/cjs/mds-pref-language.cjs.entry.js +2 -2
- package/dist/cjs/mds-pref-mode.cjs.entry.js +3 -3
- package/dist/cjs/mds-pref-theme-item.cjs.entry.js +4 -3
- package/dist/cjs/mds-pref-theme.cjs.entry.js +29 -2
- package/dist/cjs/mds-pref.cjs.entry.js +24 -53
- package/dist/cjs/mds-price-table-features-cell.cjs.entry.js +2 -2
- package/dist/cjs/mds-price-table-features-row.cjs.entry.js +2 -2
- package/dist/cjs/mds-price-table-features.cjs.entry.js +2 -2
- package/dist/cjs/mds-price-table-header.cjs.entry.js +1 -1
- package/dist/cjs/mds-price-table-list-item.cjs.entry.js +2 -2
- package/dist/cjs/mds-price-table-list.cjs.entry.js +2 -2
- package/dist/cjs/mds-price-table.cjs.entry.js +1 -1
- package/dist/cjs/mds-progress_2.cjs.entry.js +4 -4
- package/dist/cjs/mds-push-notification-item.cjs.entry.js +4 -4
- package/dist/cjs/mds-push-notification.cjs.entry.js +2 -2
- package/dist/cjs/mds-quote.cjs.entry.js +2 -2
- package/dist/cjs/mds-radial-menu-item.cjs.entry.js +2 -2
- package/dist/cjs/mds-radial-menu.cjs.entry.js +40 -4
- package/dist/cjs/mds-separator.cjs.entry.js +2 -2
- package/dist/cjs/mds-status-bar.cjs.entry.js +2 -2
- package/dist/cjs/mds-stepper-bar-item.cjs.entry.js +2 -2
- package/dist/cjs/mds-stepper-bar.cjs.entry.js +2 -2
- package/dist/cjs/mds-tab-bar-item.cjs.entry.js +2 -2
- package/dist/cjs/mds-tab-bar.cjs.entry.js +2 -2
- package/dist/cjs/mds-tab_2.cjs.entry.js +20 -7
- package/dist/cjs/mds-table-body.cjs.entry.js +2 -2
- package/dist/cjs/mds-table-footer.cjs.entry.js +2 -2
- package/dist/cjs/mds-table-header-cell.cjs.entry.js +116 -77
- package/dist/cjs/mds-table-header.cjs.entry.js +2 -2
- package/dist/cjs/mds-table-row.cjs.entry.js +3 -3
- package/dist/cjs/mds-table.cjs.entry.js +9 -2
- package/dist/cjs/mds-text.cjs.entry.js +37 -27
- package/dist/cjs/mds-toast.cjs.entry.js +2 -2
- package/dist/cjs/mds-tooltip.cjs.entry.js +17 -4
- package/dist/cjs/mds-tree-item.cjs.entry.js +2 -2
- package/dist/cjs/mds-tree.cjs.entry.js +2 -2
- package/dist/cjs/mds-url-view.cjs.entry.js +2 -2
- package/dist/cjs/mds-usage.cjs.entry.js +23 -4
- package/dist/cjs/mds-video-wall.cjs.entry.js +2 -2
- package/dist/cjs/mds-zero.cjs.entry.js +2 -2
- package/dist/cjs/string-RoXIuD3q.js +7 -0
- package/dist/collection/common/floating-controller.js +17 -3
- package/dist/collection/common/hash.js +15 -0
- package/dist/collection/common/string.js +3 -1
- package/dist/collection/common/yugop/random-text.js +5 -0
- package/dist/collection/components/mds-accordion/AGENTS.md +1 -1
- package/dist/collection/components/mds-accordion/documentation.json +1 -1
- package/dist/collection/components/mds-accordion/mds-accordion.css +5 -5
- package/dist/collection/components/mds-accordion-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-accordion-item/documentation.json +1 -1
- package/dist/collection/components/mds-accordion-item/mds-accordion-item.css +11 -11
- package/dist/collection/components/mds-accordion-timer/AGENTS.md +1 -1
- package/dist/collection/components/mds-accordion-timer/documentation.json +1 -1
- package/dist/collection/components/mds-accordion-timer/mds-accordion-timer.css +2 -2
- package/dist/collection/components/mds-accordion-timer-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-accordion-timer-item/documentation.json +1 -1
- package/dist/collection/components/mds-accordion-timer-item/mds-accordion-timer-item.css +6 -6
- package/dist/collection/components/mds-author/AGENTS.md +1 -1
- package/dist/collection/components/mds-author/documentation.json +2 -2
- package/dist/collection/components/mds-author/mds-author.css +2 -1
- package/dist/collection/components/mds-avatar/AGENTS.md +1 -1
- package/dist/collection/components/mds-avatar/documentation.json +2 -2
- package/dist/collection/components/mds-avatar/mds-avatar.css +18 -17
- package/dist/collection/components/mds-avatar-stack/AGENTS.md +1 -1
- package/dist/collection/components/mds-avatar-stack/documentation.json +1 -1
- package/dist/collection/components/mds-avatar-stack/mds-avatar-stack.css +3 -3
- package/dist/collection/components/mds-avatar-stack-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-avatar-stack-item/documentation.json +1 -1
- package/dist/collection/components/mds-avatar-stack-item/mds-avatar-stack-item.css +6 -6
- package/dist/collection/components/mds-badge/AGENTS.md +1 -1
- package/dist/collection/components/mds-badge/documentation.json +1 -1
- package/dist/collection/components/mds-badge/mds-badge.css +13 -13
- package/dist/collection/components/mds-banner/AGENTS.md +1 -1
- package/dist/collection/components/mds-banner/documentation.json +1 -1
- package/dist/collection/components/mds-banner/mds-banner.css +56 -56
- package/dist/collection/components/mds-benchmark-bar/AGENTS.md +1 -1
- package/dist/collection/components/mds-benchmark-bar/documentation.json +1 -1
- package/dist/collection/components/mds-bibliography/AGENTS.md +1 -1
- package/dist/collection/components/mds-bibliography/documentation.json +2 -2
- package/dist/collection/components/mds-bibliography/mds-bibliography.css +8 -6
- package/dist/collection/components/mds-breadcrumb/AGENTS.md +1 -1
- package/dist/collection/components/mds-breadcrumb/documentation.json +1 -1
- package/dist/collection/components/mds-breadcrumb/mds-breadcrumb.css +6 -6
- package/dist/collection/components/mds-breadcrumb-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-breadcrumb-item/documentation.json +1 -1
- package/dist/collection/components/mds-breadcrumb-item/mds-breadcrumb-item.css +14 -13
- package/dist/collection/components/mds-button/AGENTS.md +2 -2
- package/dist/collection/components/mds-button/antipattern.md +1 -1
- package/dist/collection/components/mds-button/documentation.json +4 -4
- package/dist/collection/components/mds-button/mds-button.css +226 -417
- package/dist/collection/components/mds-button/mds-button.js +47 -18
- package/dist/collection/components/mds-button/pattern.md +7 -0
- package/dist/collection/components/mds-button-dropdown/AGENTS.md +2 -2
- package/dist/collection/components/mds-button-dropdown/documentation.json +2 -2
- package/dist/collection/components/mds-button-dropdown/mds-button-dropdown.css +10 -10
- package/dist/collection/components/mds-button-dropdown/mds-button-dropdown.js +12 -1
- package/dist/collection/components/mds-button-group/AGENTS.md +1 -1
- package/dist/collection/components/mds-button-group/documentation.json +1 -1
- package/dist/collection/components/mds-button-group/mds-button-group.js +1 -1
- package/dist/collection/components/mds-calendar/AGENTS.md +2 -2
- package/dist/collection/components/mds-calendar/documentation.json +2 -2
- package/dist/collection/components/mds-calendar/mds-calendar.css +5 -5
- package/dist/collection/components/mds-calendar/mds-calendar.js +17 -4
- package/dist/collection/components/mds-calendar-cell/AGENTS.md +1 -1
- package/dist/collection/components/mds-calendar-cell/documentation.json +1 -1
- package/dist/collection/components/mds-calendar-cell/mds-calendar-cell.css +58 -58
- package/dist/collection/components/mds-calendar-cell/mds-calendar-cell.js +1 -1
- package/dist/collection/components/mds-card/AGENTS.md +1 -1
- package/dist/collection/components/mds-card/documentation.json +1 -1
- package/dist/collection/components/mds-card/mds-card.css +2 -2
- package/dist/collection/components/mds-card/mds-card.js +1 -1
- package/dist/collection/components/mds-card-content/AGENTS.md +1 -1
- package/dist/collection/components/mds-card-content/documentation.json +1 -1
- package/dist/collection/components/mds-card-content/mds-card-content.js +1 -1
- package/dist/collection/components/mds-card-footer/AGENTS.md +1 -1
- package/dist/collection/components/mds-card-footer/documentation.json +1 -1
- package/dist/collection/components/mds-card-footer/mds-card-footer.js +1 -1
- package/dist/collection/components/mds-card-header/AGENTS.md +1 -1
- package/dist/collection/components/mds-card-header/documentation.json +1 -1
- package/dist/collection/components/mds-card-header/mds-card-header.js +1 -1
- package/dist/collection/components/mds-card-media/AGENTS.md +1 -1
- package/dist/collection/components/mds-card-media/documentation.json +1 -1
- package/dist/collection/components/mds-card-media/mds-card-media.js +1 -1
- package/dist/collection/components/mds-chip/AGENTS.md +1 -1
- package/dist/collection/components/mds-chip/documentation.json +1 -1
- package/dist/collection/components/mds-chip/mds-chip.css +90 -90
- package/dist/collection/components/mds-chip/mds-chip.js +2 -2
- package/dist/collection/components/mds-details/AGENTS.md +1 -1
- package/dist/collection/components/mds-details/documentation.json +1 -1
- package/dist/collection/components/mds-details/mds-details.css +6 -6
- package/dist/collection/components/mds-details/mds-details.js +1 -1
- package/dist/collection/components/mds-dropdown/AGENTS.md +1 -1
- package/dist/collection/components/mds-dropdown/documentation.json +2 -2
- package/dist/collection/components/mds-dropdown/mds-dropdown.css +26 -26
- package/dist/collection/components/mds-dropdown/mds-dropdown.js +2 -2
- package/dist/collection/components/mds-emoji/AGENTS.md +2 -2
- package/dist/collection/components/mds-emoji/documentation.json +3 -3
- package/dist/collection/components/mds-emoji/mds-emoji.css +5 -5
- package/dist/collection/components/mds-emoji/mds-emoji.js +1 -1
- package/dist/collection/components/mds-entity/AGENTS.md +1 -1
- package/dist/collection/components/mds-entity/documentation.json +1 -1
- package/dist/collection/components/mds-entity/mds-entity.css +8 -8
- package/dist/collection/components/mds-entity/mds-entity.js +1 -1
- package/dist/collection/components/mds-file/AGENTS.md +2 -2
- package/dist/collection/components/mds-file/documentation.json +3 -3
- package/dist/collection/components/mds-file/mds-file.css +13 -13
- package/dist/collection/components/mds-file/mds-file.js +15 -9
- package/dist/collection/components/mds-file/pattern.md +1 -1
- package/dist/collection/components/mds-file-preview/AGENTS.md +1 -1
- package/dist/collection/components/mds-file-preview/documentation.json +1 -1
- package/dist/collection/components/mds-file-preview/mds-file-preview.css +21 -21
- package/dist/collection/components/mds-file-preview/mds-file-preview.js +2 -2
- package/dist/collection/components/mds-filter/AGENTS.md +5 -3
- package/dist/collection/components/mds-filter/documentation.json +3 -3
- package/dist/collection/components/mds-filter/mds-filter.css +16 -16
- package/dist/collection/components/mds-filter/mds-filter.js +97 -19
- package/dist/collection/components/mds-filter/pattern.md +34 -4
- package/dist/collection/components/mds-filter-item/AGENTS.md +9 -8
- package/dist/collection/components/mds-filter-item/documentation.json +4 -4
- package/dist/collection/components/mds-filter-item/mds-filter-item.css +27 -17
- package/dist/collection/components/mds-filter-item/mds-filter-item.js +65 -3
- package/dist/collection/components/mds-filter-item/pattern.md +5 -5
- package/dist/collection/components/mds-header/AGENTS.md +1 -1
- package/dist/collection/components/mds-header/documentation.json +1 -1
- package/dist/collection/components/mds-header/mds-header.css +21 -13
- package/dist/collection/components/mds-header/mds-header.js +1 -1
- package/dist/collection/components/mds-header-bar/AGENTS.md +2 -2
- package/dist/collection/components/mds-header-bar/documentation.json +2 -2
- package/dist/collection/components/mds-header-bar/mds-header-bar.css +5 -5
- package/dist/collection/components/mds-header-bar/mds-header-bar.js +12 -1
- package/dist/collection/components/mds-help/AGENTS.md +1 -1
- package/dist/collection/components/mds-help/documentation.json +2 -2
- package/dist/collection/components/mds-help/mds-help.css +1 -1
- package/dist/collection/components/mds-help/mds-help.js +1 -1
- package/dist/collection/components/mds-horizontal-scroll/AGENTS.md +2 -2
- package/dist/collection/components/mds-horizontal-scroll/documentation.json +2 -2
- package/dist/collection/components/mds-horizontal-scroll/mds-horizontal-scroll.css +10 -10
- package/dist/collection/components/mds-horizontal-scroll/mds-horizontal-scroll.js +12 -1
- package/dist/collection/components/mds-hr/AGENTS.md +1 -1
- package/dist/collection/components/mds-hr/documentation.json +1 -1
- package/dist/collection/components/mds-hr/mds-hr.css +1 -1
- package/dist/collection/components/mds-hr/mds-hr.js +1 -1
- package/dist/collection/components/mds-icon/AGENTS.md +1 -1
- package/dist/collection/components/mds-icon/documentation.json +2 -2
- package/dist/collection/components/mds-icon/mds-icon.js +1 -1
- package/dist/collection/components/mds-img/AGENTS.md +1 -1
- package/dist/collection/components/mds-img/documentation.json +1 -1
- package/dist/collection/components/mds-img/mds-img.css +6 -6
- package/dist/collection/components/mds-input/AGENTS.md +3 -1
- package/dist/collection/components/mds-input/documentation.json +52 -4
- package/dist/collection/components/mds-input/mds-input.css +133 -62
- package/dist/collection/components/mds-input/mds-input.js +38 -2
- package/dist/collection/components/mds-input/pattern.md +15 -0
- package/dist/collection/components/mds-input-date/AGENTS.md +5 -2
- package/dist/collection/components/mds-input-date/documentation.json +50 -2
- package/dist/collection/components/mds-input-date/mds-input-date.css +52 -26
- package/dist/collection/components/mds-input-date/mds-input-date.js +46 -2
- package/dist/collection/components/mds-input-date-range/AGENTS.md +4 -2
- package/dist/collection/components/mds-input-date-range/documentation.json +50 -2
- package/dist/collection/components/mds-input-date-range/mds-input-date-range.css +51 -25
- package/dist/collection/components/mds-input-date-range/mds-input-date-range.js +34 -1
- package/dist/collection/components/mds-input-date-range-preselection/AGENTS.md +1 -1
- package/dist/collection/components/mds-input-date-range-preselection/documentation.json +1 -1
- package/dist/collection/components/mds-input-date-range-preselection/mds-input-date-range-preselection.css +18 -18
- package/dist/collection/components/mds-input-date-range-preselection/mds-input-date-range-preselection.js +1 -1
- package/dist/collection/components/mds-input-field/AGENTS.md +1 -1
- package/dist/collection/components/mds-input-field/documentation.json +1 -1
- package/dist/collection/components/mds-input-field/mds-input-field.css +7 -7
- package/dist/collection/components/mds-input-field/mds-input-field.js +1 -1
- package/dist/collection/components/mds-input-otp/AGENTS.md +1 -1
- package/dist/collection/components/mds-input-otp/documentation.json +1 -1
- package/dist/collection/components/mds-input-otp/mds-input-otp.js +1 -1
- package/dist/collection/components/mds-input-range/AGENTS.md +1 -1
- package/dist/collection/components/mds-input-range/documentation.json +1 -1
- package/dist/collection/components/mds-input-range/mds-input-range.css +13 -12
- package/dist/collection/components/mds-input-range/mds-input-range.js +1 -1
- package/dist/collection/components/mds-input-select/AGENTS.md +7 -4
- package/dist/collection/components/mds-input-select/documentation.json +58 -7
- package/dist/collection/components/mds-input-select/mds-input-select.css +103 -29
- package/dist/collection/components/mds-input-select/mds-input-select.js +61 -7
- package/dist/collection/components/mds-input-select/pattern.md +3 -3
- package/dist/collection/components/mds-input-switch/AGENTS.md +2 -2
- package/dist/collection/components/mds-input-switch/documentation.json +2 -2
- package/dist/collection/components/mds-input-switch/mds-input-switch.css +86 -65
- package/dist/collection/components/mds-input-switch/mds-input-switch.js +19 -6
- package/dist/collection/components/mds-input-tip/AGENTS.md +1 -1
- package/dist/collection/components/mds-input-tip/documentation.json +1 -1
- package/dist/collection/components/mds-input-tip/mds-input-tip.css +1 -1
- package/dist/collection/components/mds-input-tip/mds-input-tip.js +1 -1
- package/dist/collection/components/mds-input-tip-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-input-tip-item/documentation.json +1 -1
- package/dist/collection/components/mds-input-tip-item/mds-input-tip-item.css +21 -20
- package/dist/collection/components/mds-input-tip-item/mds-input-tip-item.js +2 -2
- package/dist/collection/components/mds-input-upload/AGENTS.md +1 -1
- package/dist/collection/components/mds-input-upload/documentation.json +1 -1
- package/dist/collection/components/mds-input-upload/mds-input-upload.css +13 -12
- package/dist/collection/components/mds-input-upload/mds-input-upload.js +5 -5
- package/dist/collection/components/mds-keyboard/AGENTS.md +1 -1
- package/dist/collection/components/mds-keyboard/documentation.json +1 -1
- package/dist/collection/components/mds-keyboard/mds-keyboard.css +4 -3
- package/dist/collection/components/mds-keyboard/mds-keyboard.js +1 -1
- package/dist/collection/components/mds-keyboard-key/AGENTS.md +1 -1
- package/dist/collection/components/mds-keyboard-key/documentation.json +1 -1
- package/dist/collection/components/mds-keyboard-key/mds-keyboard-key.css +2 -1
- package/dist/collection/components/mds-keyboard-key/mds-keyboard-key.js +1 -1
- package/dist/collection/components/mds-kpi/AGENTS.md +1 -1
- package/dist/collection/components/mds-kpi/documentation.json +1 -1
- package/dist/collection/components/mds-kpi/mds-kpi.js +1 -1
- package/dist/collection/components/mds-kpi-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-kpi-item/documentation.json +1 -1
- package/dist/collection/components/mds-kpi-item/mds-kpi-item.css +13 -13
- package/dist/collection/components/mds-kpi-item/mds-kpi-item.js +1 -1
- package/dist/collection/components/mds-label/AGENTS.md +1 -1
- package/dist/collection/components/mds-label/documentation.json +1 -1
- package/dist/collection/components/mds-label/mds-label.css +12 -12
- package/dist/collection/components/mds-list/AGENTS.md +2 -2
- package/dist/collection/components/mds-list/documentation.json +2 -2
- package/dist/collection/components/mds-list/mds-list.js +1 -1
- package/dist/collection/components/mds-list-item/AGENTS.md +2 -1
- package/dist/collection/components/mds-list-item/documentation.json +3 -3
- package/dist/collection/components/mds-list-item/mds-list-item.css +0 -18
- package/dist/collection/components/mds-list-item/mds-list-item.js +1 -2
- package/dist/collection/components/mds-list-item/pattern.md +11 -0
- package/dist/collection/components/mds-mention/AGENTS.md +1 -1
- package/dist/collection/components/mds-mention/documentation.json +1 -1
- package/dist/collection/components/mds-mention/mds-mention.css +2 -2
- package/dist/collection/components/mds-mention/mds-mention.js +1 -1
- package/dist/collection/components/mds-modal/AGENTS.md +2 -2
- package/dist/collection/components/mds-modal/documentation.json +2 -2
- package/dist/collection/components/mds-modal/mds-modal.css +5 -5
- package/dist/collection/components/mds-modal/mds-modal.js +14 -3
- package/dist/collection/components/mds-note/AGENTS.md +1 -1
- package/dist/collection/components/mds-note/documentation.json +1 -1
- package/dist/collection/components/mds-note/mds-note.css +3 -3
- package/dist/collection/components/mds-note/mds-note.js +1 -1
- package/dist/collection/components/mds-notification/AGENTS.md +1 -1
- package/dist/collection/components/mds-notification/documentation.json +2 -2
- package/dist/collection/components/mds-notification/mds-notification.css +4 -4
- package/dist/collection/components/mds-notification/mds-notification.js +1 -1
- package/dist/collection/components/mds-paginator/AGENTS.md +1 -1
- package/dist/collection/components/mds-paginator/documentation.json +1 -1
- package/dist/collection/components/mds-paginator/mds-paginator.css +6 -6
- package/dist/collection/components/mds-paginator/mds-paginator.js +1 -1
- package/dist/collection/components/mds-paginator-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-paginator-item/documentation.json +1 -1
- package/dist/collection/components/mds-paginator-item/mds-paginator-item.css +31 -30
- package/dist/collection/components/mds-paginator-item/mds-paginator-item.js +1 -1
- package/dist/collection/components/mds-policy-ai/AGENTS.md +1 -1
- package/dist/collection/components/mds-policy-ai/documentation.json +1 -1
- package/dist/collection/components/mds-policy-ai/mds-policy-ai.css +8 -8
- package/dist/collection/components/mds-policy-ai/mds-policy-ai.js +1 -1
- package/dist/collection/components/mds-pref/AGENTS.md +2 -2
- package/dist/collection/components/mds-pref/documentation.json +14 -3
- package/dist/collection/components/mds-pref/mds-pref.js +39 -53
- package/dist/collection/components/mds-pref-animation/AGENTS.md +1 -1
- package/dist/collection/components/mds-pref-animation/documentation.json +1 -1
- package/dist/collection/components/mds-pref-animation/mds-pref-animation.css +7 -7
- package/dist/collection/components/mds-pref-animation/mds-pref-animation.js +1 -1
- package/dist/collection/components/mds-pref-consumption/AGENTS.md +1 -1
- package/dist/collection/components/mds-pref-consumption/documentation.json +1 -1
- package/dist/collection/components/mds-pref-consumption/mds-pref-consumption.css +4 -4
- package/dist/collection/components/mds-pref-consumption/mds-pref-consumption.js +1 -1
- package/dist/collection/components/mds-pref-contrast/AGENTS.md +1 -1
- package/dist/collection/components/mds-pref-contrast/documentation.json +1 -1
- package/dist/collection/components/mds-pref-contrast/mds-pref-contrast.css +5 -5
- package/dist/collection/components/mds-pref-contrast/mds-pref-contrast.js +1 -1
- package/dist/collection/components/mds-pref-language/AGENTS.md +3 -3
- package/dist/collection/components/mds-pref-language/documentation.json +2 -2
- package/dist/collection/components/mds-pref-language/mds-pref-language.css +10 -2
- package/dist/collection/components/mds-pref-language/mds-pref-language.js +1 -1
- package/dist/collection/components/mds-pref-language-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-pref-language-item/documentation.json +1 -1
- package/dist/collection/components/mds-pref-language-item/mds-pref-language-item.js +1 -1
- package/dist/collection/components/mds-pref-mode/AGENTS.md +3 -3
- package/dist/collection/components/mds-pref-mode/documentation.json +2 -2
- package/dist/collection/components/mds-pref-mode/mds-pref-mode.css +5 -5
- package/dist/collection/components/mds-pref-mode/mds-pref-mode.js +2 -2
- package/dist/collection/components/mds-pref-theme/AGENTS.md +4 -3
- package/dist/collection/components/mds-pref-theme/documentation.json +2 -2
- package/dist/collection/components/mds-pref-theme/mds-pref-theme.css +10 -2
- package/dist/collection/components/mds-pref-theme/mds-pref-theme.js +29 -2
- package/dist/collection/components/mds-pref-theme-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-pref-theme-item/documentation.json +1 -1
- package/dist/collection/components/mds-pref-theme-item/mds-pref-theme-item.css +10 -9
- package/dist/collection/components/mds-pref-theme-item/mds-pref-theme-item.js +3 -2
- package/dist/collection/components/mds-price-table/AGENTS.md +1 -1
- package/dist/collection/components/mds-price-table/documentation.json +1 -1
- package/dist/collection/components/mds-price-table/mds-price-table.js +1 -1
- package/dist/collection/components/mds-price-table-features/AGENTS.md +1 -1
- package/dist/collection/components/mds-price-table-features/documentation.json +1 -1
- package/dist/collection/components/mds-price-table-features/mds-price-table-features.css +2 -2
- package/dist/collection/components/mds-price-table-features/mds-price-table-features.js +1 -1
- package/dist/collection/components/mds-price-table-features-cell/AGENTS.md +1 -1
- package/dist/collection/components/mds-price-table-features-cell/documentation.json +1 -1
- package/dist/collection/components/mds-price-table-features-cell/mds-price-table-features-cell.css +11 -11
- package/dist/collection/components/mds-price-table-features-cell/mds-price-table-features-cell.js +1 -1
- package/dist/collection/components/mds-price-table-features-row/AGENTS.md +1 -1
- package/dist/collection/components/mds-price-table-features-row/documentation.json +1 -1
- package/dist/collection/components/mds-price-table-features-row/mds-price-table-features-row.css +12 -12
- package/dist/collection/components/mds-price-table-features-row/mds-price-table-features-row.js +1 -1
- package/dist/collection/components/mds-price-table-header/AGENTS.md +1 -1
- package/dist/collection/components/mds-price-table-header/documentation.json +1 -1
- package/dist/collection/components/mds-price-table-header/mds-price-table-header.js +1 -1
- package/dist/collection/components/mds-price-table-list/AGENTS.md +1 -1
- package/dist/collection/components/mds-price-table-list/documentation.json +1 -1
- package/dist/collection/components/mds-price-table-list/mds-price-table-list.css +8 -8
- package/dist/collection/components/mds-price-table-list/mds-price-table-list.js +1 -1
- package/dist/collection/components/mds-price-table-list-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-price-table-list-item/documentation.json +1 -1
- package/dist/collection/components/mds-price-table-list-item/mds-price-table-list-item.css +2 -2
- package/dist/collection/components/mds-price-table-list-item/mds-price-table-list-item.js +1 -1
- package/dist/collection/components/mds-progress/AGENTS.md +1 -1
- package/dist/collection/components/mds-progress/documentation.json +1 -1
- package/dist/collection/components/mds-progress/mds-progress.css +20 -20
- package/dist/collection/components/mds-progress/mds-progress.js +1 -1
- package/dist/collection/components/mds-push-notification/AGENTS.md +1 -1
- package/dist/collection/components/mds-push-notification/documentation.json +1 -1
- package/dist/collection/components/mds-push-notification/mds-push-notification.js +1 -1
- package/dist/collection/components/mds-push-notification-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-push-notification-item/documentation.json +1 -1
- package/dist/collection/components/mds-push-notification-item/mds-push-notification-item.css +16 -16
- package/dist/collection/components/mds-push-notification-item/mds-push-notification-item.js +2 -2
- package/dist/collection/components/mds-quote/AGENTS.md +1 -1
- package/dist/collection/components/mds-quote/documentation.json +1 -1
- package/dist/collection/components/mds-quote/mds-quote.css +6 -4
- package/dist/collection/components/mds-quote/mds-quote.js +1 -1
- package/dist/collection/components/mds-radial-menu/AGENTS.md +2 -2
- package/dist/collection/components/mds-radial-menu/documentation.json +2 -2
- package/dist/collection/components/mds-radial-menu/mds-radial-menu.css +5 -3
- package/dist/collection/components/mds-radial-menu/mds-radial-menu.js +12 -1
- package/dist/collection/components/mds-radial-menu-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-radial-menu-item/documentation.json +1 -1
- package/dist/collection/components/mds-radial-menu-item/mds-radial-menu-item.js +1 -1
- package/dist/collection/components/mds-radial-progress/AGENTS.md +1 -1
- package/dist/collection/components/mds-radial-progress/documentation.json +1 -1
- package/dist/collection/components/mds-radial-progress/mds-radial-progress.css +15 -15
- package/dist/collection/components/mds-radial-progress/mds-radial-progress.js +1 -1
- package/dist/collection/components/mds-separator/AGENTS.md +1 -1
- package/dist/collection/components/mds-separator/documentation.json +1 -1
- package/dist/collection/components/mds-separator/mds-separator.css +2 -2
- package/dist/collection/components/mds-separator/mds-separator.js +1 -1
- package/dist/collection/components/mds-spinner/AGENTS.md +1 -1
- package/dist/collection/components/mds-spinner/documentation.json +1 -1
- package/dist/collection/components/mds-spinner/mds-spinner.css +3 -3
- package/dist/collection/components/mds-spinner/mds-spinner.js +1 -1
- package/dist/collection/components/mds-status-bar/AGENTS.md +1 -1
- package/dist/collection/components/mds-status-bar/documentation.json +1 -1
- package/dist/collection/components/mds-status-bar/mds-status-bar.css +7 -6
- package/dist/collection/components/mds-status-bar/mds-status-bar.js +1 -1
- package/dist/collection/components/mds-stepper-bar/AGENTS.md +1 -1
- package/dist/collection/components/mds-stepper-bar/documentation.json +1 -1
- package/dist/collection/components/mds-stepper-bar/mds-stepper-bar.css +6 -6
- package/dist/collection/components/mds-stepper-bar/mds-stepper-bar.js +1 -1
- package/dist/collection/components/mds-stepper-bar-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-stepper-bar-item/documentation.json +1 -1
- package/dist/collection/components/mds-stepper-bar-item/mds-stepper-bar-item.css +15 -15
- package/dist/collection/components/mds-stepper-bar-item/mds-stepper-bar-item.js +1 -1
- package/dist/collection/components/mds-tab/AGENTS.md +2 -2
- package/dist/collection/components/mds-tab/documentation.json +2 -2
- package/dist/collection/components/mds-tab/mds-tab.css +51 -23
- package/dist/collection/components/mds-tab/mds-tab.js +18 -4
- package/dist/collection/components/mds-tab-bar/AGENTS.md +1 -1
- package/dist/collection/components/mds-tab-bar/documentation.json +1 -1
- package/dist/collection/components/mds-tab-bar/mds-tab-bar.css +1 -1
- package/dist/collection/components/mds-tab-bar/mds-tab-bar.js +1 -1
- package/dist/collection/components/mds-tab-bar-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-tab-bar-item/documentation.json +1 -1
- package/dist/collection/components/mds-tab-bar-item/mds-tab-bar-item.css +14 -14
- package/dist/collection/components/mds-tab-bar-item/mds-tab-bar-item.js +1 -1
- package/dist/collection/components/mds-tab-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-tab-item/documentation.json +1 -1
- package/dist/collection/components/mds-tab-item/mds-tab-item.css +2 -2
- package/dist/collection/components/mds-tab-item/mds-tab-item.js +1 -1
- package/dist/collection/components/mds-table/AGENTS.md +4 -2
- package/dist/collection/components/mds-table/documentation.json +48 -4
- package/dist/collection/components/mds-table/mds-table.css +33 -22
- package/dist/collection/components/mds-table/mds-table.js +35 -1
- package/dist/collection/components/mds-table/pattern.md +30 -0
- package/dist/collection/components/mds-table-body/AGENTS.md +1 -1
- package/dist/collection/components/mds-table-body/documentation.json +1 -1
- package/dist/collection/components/mds-table-body/mds-table-body.css +8 -8
- package/dist/collection/components/mds-table-body/mds-table-body.js +1 -1
- package/dist/collection/components/mds-table-cell/AGENTS.md +1 -1
- package/dist/collection/components/mds-table-cell/documentation.json +1 -1
- package/dist/collection/components/mds-table-cell/mds-table-cell.js +1 -1
- package/dist/collection/components/mds-table-footer/AGENTS.md +1 -1
- package/dist/collection/components/mds-table-footer/documentation.json +1 -1
- package/dist/collection/components/mds-table-footer/mds-table-footer.js +1 -1
- package/dist/collection/components/mds-table-header/AGENTS.md +1 -1
- package/dist/collection/components/mds-table-header/documentation.json +1 -1
- package/dist/collection/components/mds-table-header/mds-table-header.js +1 -1
- package/dist/collection/components/mds-table-header-cell/AGENTS.md +14 -5
- package/dist/collection/components/mds-table-header-cell/antipattern.md +17 -10
- package/dist/collection/components/mds-table-header-cell/documentation.json +54 -6
- package/dist/collection/components/mds-table-header-cell/mds-table-header-cell.js +159 -82
- package/dist/collection/components/mds-table-header-cell/meta/event-detail.js +1 -0
- package/dist/collection/components/mds-table-header-cell/pattern.md +27 -6
- package/dist/collection/components/mds-table-row/AGENTS.md +1 -1
- package/dist/collection/components/mds-table-row/documentation.json +1 -1
- package/dist/collection/components/mds-table-row/mds-table-row.css +12 -12
- package/dist/collection/components/mds-table-row/mds-table-row.js +2 -2
- package/dist/collection/components/mds-text/AGENTS.md +3 -3
- package/dist/collection/components/mds-text/documentation.json +2 -2
- package/dist/collection/components/mds-text/mds-text.css +3 -3
- package/dist/collection/components/mds-text/mds-text.js +31 -26
- package/dist/collection/components/mds-toast/AGENTS.md +1 -1
- package/dist/collection/components/mds-toast/documentation.json +1 -1
- package/dist/collection/components/mds-toast/mds-toast.css +18 -18
- package/dist/collection/components/mds-toast/mds-toast.js +1 -1
- package/dist/collection/components/mds-tooltip/AGENTS.md +4 -2
- package/dist/collection/components/mds-tooltip/antipattern.md +14 -0
- package/dist/collection/components/mds-tooltip/documentation.json +46 -5
- package/dist/collection/components/mds-tooltip/mds-tooltip.css +10 -10
- package/dist/collection/components/mds-tooltip/mds-tooltip.js +41 -1
- package/dist/collection/components/mds-tooltip/pattern.md +9 -0
- package/dist/collection/components/mds-tree/AGENTS.md +1 -1
- package/dist/collection/components/mds-tree/documentation.json +1 -1
- package/dist/collection/components/mds-tree/mds-tree.css +13 -13
- package/dist/collection/components/mds-tree/mds-tree.js +1 -1
- package/dist/collection/components/mds-tree-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-tree-item/documentation.json +1 -1
- package/dist/collection/components/mds-tree-item/mds-tree-item.js +1 -1
- package/dist/collection/components/mds-url-view/AGENTS.md +1 -1
- package/dist/collection/components/mds-url-view/documentation.json +1 -1
- package/dist/collection/components/mds-url-view/mds-url-view.css +7 -7
- package/dist/collection/components/mds-url-view/mds-url-view.js +1 -1
- package/dist/collection/components/mds-usage/AGENTS.md +5 -3
- package/dist/collection/components/mds-usage/antipattern.md +17 -1
- package/dist/collection/components/mds-usage/documentation.json +31 -5
- package/dist/collection/components/mds-usage/mds-usage.css +6 -6
- package/dist/collection/components/mds-usage/mds-usage.js +26 -4
- package/dist/collection/components/mds-usage/meta/variants.js +14 -18
- package/dist/collection/components/mds-usage/pattern.md +10 -0
- package/dist/collection/components/mds-video-wall/AGENTS.md +1 -1
- package/dist/collection/components/mds-video-wall/documentation.json +1 -1
- package/dist/collection/components/mds-video-wall/mds-video-wall.css +3 -3
- package/dist/collection/components/mds-video-wall/mds-video-wall.js +1 -1
- package/dist/collection/components/mds-zero/AGENTS.md +1 -1
- package/dist/collection/components/mds-zero/documentation.json +1 -1
- package/dist/collection/components/mds-zero/mds-zero.css +3 -3
- package/dist/collection/components/mds-zero/mds-zero.js +1 -1
- package/dist/collection/type/floating-ui.js +1 -0
- package/dist/collection/type/input.js +2 -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-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 +2 -2
- package/dist/components/mds-entity.js +1 -1
- package/dist/components/mds-file-preview.js +1 -1
- package/dist/components/mds-file.js +1 -18
- 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.js +1 -1
- package/dist/components/mds-pref-theme-item.js +1 -1
- 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--5KZXaZp.js +1 -0
- package/dist/components/p--OCrgFeE.js +1 -0
- package/dist/components/p-6LGfUDQ4.js +1 -0
- package/dist/components/p-6pgPWpGI.js +1 -0
- package/dist/components/p-B8BWxSho.js +1 -0
- package/dist/components/p-B9uIL9KO.js +1 -0
- package/dist/components/p-BBDliSai.js +1 -0
- package/dist/components/p-BCwcnHFh.js +1 -0
- package/dist/components/p-BRf-u585.js +1 -0
- package/dist/components/p-BSeokAdy.js +1 -0
- package/dist/components/p-BXUJgu8l.js +1 -0
- package/dist/components/p-BXYUyw7p.js +1 -0
- package/dist/components/{p-s2Gu6hY7.js → p-BcUY-9n7.js} +1 -1
- package/dist/components/p-BfgJ-hHQ.js +1 -0
- package/dist/components/p-CIfGjW_Z.js +1 -0
- package/dist/components/p-CMp9rP7L.js +1 -0
- package/dist/components/p-CUmJoPAI.js +1 -0
- package/dist/components/p-CZjHixVB.js +1 -0
- package/dist/components/p-Ck0q_n7I.js +1 -0
- package/dist/components/p-CrCa_6a1.js +8 -0
- package/dist/components/p-Cv7lqHIc.js +1 -0
- package/dist/components/p-Cw6_ooFx.js +1 -0
- package/dist/components/p-DGYRngAi.js +1 -0
- package/dist/components/p-DHu8X7zF.js +1 -0
- package/dist/components/{p-C7EyV0z3.js → p-DLCcW1Q5.js} +1 -1
- package/dist/components/p-DOzcuSrZ.js +1 -0
- package/dist/components/{p-BHJDW5JC.js → p-DZPHWQtD.js} +1 -1
- package/dist/components/p-DlRjt7nE.js +1 -0
- package/dist/components/{p-Bv2IVRzI.js → p-DmPLOktp.js} +1 -1
- package/dist/components/p-HSM_x8fD.js +1 -0
- package/dist/components/p-JMPfVnGv.js +1 -0
- package/dist/components/p-ay5NzZ_x.js +1 -0
- package/dist/components/p-lNY_3s6S.js +1 -0
- package/dist/components/p-qYRtWYC8.js +1 -0
- package/dist/documentation.json +460 -75
- package/dist/esm/_commonjsHelpers-B85MJLTf.js +5 -0
- package/dist/esm/{floating-controller-BTYkH_Ih.js → floating-controller-D5-8D9mH.js} +18 -4
- package/dist/esm/{floating-ui.dom-CHAGzQT-.js → floating-ui.dom-JMPfVnGv.js} +146 -94
- package/dist/esm/icon-pNJmnrhq.js +16 -0
- package/dist/esm/index-BxPbQB28.js +40 -40
- package/dist/esm/loader.js +1 -1
- package/dist/esm/magma-components.js +1 -1
- package/dist/esm/mds-accordion-item.entry.js +1 -1
- package/dist/esm/mds-accordion-timer-item.entry.js +1 -1
- package/dist/esm/mds-accordion-timer.entry.js +1 -1
- package/dist/esm/mds-accordion.entry.js +1 -1
- package/dist/esm/mds-avatar-stack-item.entry.js +1 -1
- package/dist/esm/mds-avatar-stack.entry.js +1 -1
- package/dist/esm/mds-avatar.entry.js +2 -2
- package/dist/esm/mds-badge.entry.js +1 -1
- package/dist/esm/mds-banner_3.entry.js +6 -6
- package/dist/esm/mds-bibliography.entry.js +1 -1
- package/dist/esm/mds-breadcrumb-item.entry.js +1 -1
- package/dist/esm/mds-breadcrumb.entry.js +1 -1
- package/dist/esm/mds-button-dropdown.entry.js +30 -2
- package/dist/esm/mds-button-group.entry.js +1 -1
- package/dist/esm/mds-button_3.entry.js +52 -37
- package/dist/esm/mds-calendar_2.entry.js +60 -7
- package/dist/esm/mds-card-content.entry.js +1 -1
- package/dist/esm/mds-card-footer.entry.js +1 -1
- package/dist/esm/mds-card-header.entry.js +1 -1
- package/dist/esm/mds-card-media.entry.js +2 -2
- package/dist/esm/mds-card.entry.js +2 -2
- package/dist/esm/mds-details.entry.js +2 -2
- package/dist/esm/mds-dropdown.entry.js +5 -5
- package/dist/esm/mds-emoji.entry.js +2 -2
- package/dist/esm/mds-entity.entry.js +2 -2
- package/dist/esm/mds-file-preview.entry.js +3 -3
- package/dist/esm/mds-file.entry.js +30 -7521
- package/dist/esm/mds-filter-item.entry.js +89 -3
- package/dist/esm/mds-filter.entry.js +114 -20
- package/dist/esm/mds-header-bar.entry.js +29 -2
- package/dist/esm/mds-header.entry.js +2 -2
- package/dist/esm/mds-horizontal-scroll.entry.js +38 -2
- package/dist/esm/mds-hr.entry.js +2 -2
- package/dist/esm/mds-img.entry.js +1 -1
- package/dist/esm/mds-input-date-range-preselection.entry.js +2 -2
- package/dist/esm/mds-input-date-range.entry.js +16 -2
- package/dist/esm/mds-input-date.entry.js +36 -4
- package/dist/esm/mds-input-field.entry.js +2 -2
- package/dist/esm/mds-input-otp.entry.js +1 -1
- package/dist/esm/mds-input-range.entry.js +2 -2
- package/dist/esm/mds-input-select.entry.js +32 -5
- package/dist/esm/mds-input-switch_2.entry.js +21 -8
- package/dist/esm/mds-input-tip_2.entry.js +5 -5
- package/dist/esm/mds-input-upload.entry.js +6 -6
- package/dist/esm/mds-input.entry.js +12 -3
- package/dist/esm/mds-keyboard-key.entry.js +2 -2
- package/dist/esm/mds-keyboard.entry.js +2 -2
- package/dist/esm/mds-kpi-item.entry.js +2 -2
- package/dist/esm/mds-kpi.entry.js +1 -1
- package/dist/esm/mds-label.entry.js +1 -1
- package/dist/esm/mds-list-item.entry.js +2 -3
- package/dist/esm/mds-list.entry.js +1 -1
- package/dist/esm/mds-mention.entry.js +2 -2
- package/dist/esm/mds-modal.entry.js +31 -4
- package/dist/esm/mds-note.entry.js +2 -2
- package/dist/esm/mds-notification.entry.js +3 -3
- package/dist/esm/mds-paginator-item.entry.js +2 -2
- package/dist/esm/mds-paginator.entry.js +2 -2
- package/dist/esm/mds-policy-ai.entry.js +2 -2
- package/dist/esm/mds-pref-animation.entry.js +2 -2
- package/dist/esm/mds-pref-consumption.entry.js +2 -2
- package/dist/esm/mds-pref-contrast.entry.js +2 -2
- package/dist/esm/mds-pref-language-item.entry.js +1 -1
- package/dist/esm/mds-pref-language.entry.js +2 -2
- package/dist/esm/mds-pref-mode.entry.js +3 -3
- package/dist/esm/mds-pref-theme-item.entry.js +4 -3
- package/dist/esm/mds-pref-theme.entry.js +30 -3
- package/dist/esm/mds-pref.entry.js +24 -53
- package/dist/esm/mds-price-table-features-cell.entry.js +2 -2
- package/dist/esm/mds-price-table-features-row.entry.js +2 -2
- package/dist/esm/mds-price-table-features.entry.js +2 -2
- package/dist/esm/mds-price-table-header.entry.js +1 -1
- package/dist/esm/mds-price-table-list-item.entry.js +2 -2
- package/dist/esm/mds-price-table-list.entry.js +2 -2
- package/dist/esm/mds-price-table.entry.js +1 -1
- package/dist/esm/mds-progress_2.entry.js +4 -4
- package/dist/esm/mds-push-notification-item.entry.js +4 -4
- package/dist/esm/mds-push-notification.entry.js +2 -2
- package/dist/esm/mds-quote.entry.js +2 -2
- package/dist/esm/mds-radial-menu-item.entry.js +2 -2
- package/dist/esm/mds-radial-menu.entry.js +40 -4
- package/dist/esm/mds-separator.entry.js +2 -2
- package/dist/esm/mds-status-bar.entry.js +2 -2
- package/dist/esm/mds-stepper-bar-item.entry.js +2 -2
- package/dist/esm/mds-stepper-bar.entry.js +2 -2
- package/dist/esm/mds-tab-bar-item.entry.js +2 -2
- package/dist/esm/mds-tab-bar.entry.js +2 -2
- package/dist/esm/mds-tab_2.entry.js +20 -7
- package/dist/esm/mds-table-body.entry.js +2 -2
- package/dist/esm/mds-table-footer.entry.js +2 -2
- package/dist/esm/mds-table-header-cell.entry.js +117 -78
- package/dist/esm/mds-table-header.entry.js +2 -2
- package/dist/esm/mds-table-row.entry.js +3 -3
- package/dist/esm/mds-table.entry.js +9 -2
- package/dist/esm/mds-text.entry.js +37 -27
- package/dist/esm/mds-toast.entry.js +2 -2
- package/dist/esm/mds-tooltip.entry.js +17 -4
- package/dist/esm/mds-tree-item.entry.js +2 -2
- package/dist/esm/mds-tree.entry.js +2 -2
- package/dist/esm/mds-url-view.entry.js +2 -2
- package/dist/esm/mds-usage.entry.js +23 -4
- package/dist/esm/mds-video-wall.entry.js +2 -2
- package/dist/esm/mds-zero.entry.js +2 -2
- package/dist/esm/string-6pgPWpGI.js +5 -0
- package/dist/esm-es5/_commonjsHelpers-B85MJLTf.js +1 -0
- package/dist/esm-es5/{floating-controller-BTYkH_Ih.js → floating-controller-D5-8D9mH.js} +11 -5
- package/dist/esm-es5/{floating-ui.dom-CHAGzQT-.js → floating-ui.dom-JMPfVnGv.js} +80 -48
- package/dist/esm-es5/icon-pNJmnrhq.js +1 -0
- package/dist/esm-es5/index-BxPbQB28.js +36 -36
- package/dist/esm-es5/loader.js +1 -1
- package/dist/esm-es5/magma-components.js +1 -1
- package/dist/esm-es5/mds-accordion-item.entry.js +1 -1
- package/dist/esm-es5/mds-accordion-timer-item.entry.js +2 -2
- package/dist/esm-es5/mds-accordion-timer.entry.js +2 -2
- package/dist/esm-es5/mds-accordion.entry.js +2 -2
- package/dist/esm-es5/mds-avatar-stack-item.entry.js +1 -1
- package/dist/esm-es5/mds-avatar-stack.entry.js +1 -1
- package/dist/esm-es5/mds-avatar.entry.js +2 -2
- package/dist/esm-es5/mds-badge.entry.js +1 -1
- package/dist/esm-es5/mds-banner_3.entry.js +5 -5
- package/dist/esm-es5/mds-bibliography.entry.js +2 -2
- package/dist/esm-es5/mds-breadcrumb-item.entry.js +1 -1
- package/dist/esm-es5/mds-breadcrumb.entry.js +2 -2
- package/dist/esm-es5/mds-button-dropdown.entry.js +3 -3
- package/dist/esm-es5/mds-button-group.entry.js +1 -1
- package/dist/esm-es5/mds-button_3.entry.js +30 -9
- package/dist/esm-es5/mds-calendar_2.entry.js +9 -7
- 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 +5 -5
- package/dist/esm-es5/mds-details.entry.js +2 -2
- package/dist/esm-es5/mds-dropdown.entry.js +16 -16
- package/dist/esm-es5/mds-emoji.entry.js +19 -19
- package/dist/esm-es5/mds-entity.entry.js +1 -1
- package/dist/esm-es5/mds-file-preview.entry.js +7 -7
- package/dist/esm-es5/mds-file.entry.js +15 -2835
- package/dist/esm-es5/mds-filter-item.entry.js +16 -1
- package/dist/esm-es5/mds-filter.entry.js +18 -2
- package/dist/esm-es5/mds-header-bar.entry.js +3 -3
- package/dist/esm-es5/mds-header.entry.js +7 -7
- package/dist/esm-es5/mds-horizontal-scroll.entry.js +13 -13
- package/dist/esm-es5/mds-hr.entry.js +1 -1
- package/dist/esm-es5/mds-img.entry.js +1 -1
- package/dist/esm-es5/mds-input-date-range-preselection.entry.js +1 -1
- package/dist/esm-es5/mds-input-date-range.entry.js +7 -2
- package/dist/esm-es5/mds-input-date.entry.js +8 -3
- package/dist/esm-es5/mds-input-field.entry.js +2 -2
- package/dist/esm-es5/mds-input-otp.entry.js +1 -1
- package/dist/esm-es5/mds-input-range.entry.js +7 -7
- package/dist/esm-es5/mds-input-select.entry.js +14 -5
- package/dist/esm-es5/mds-input-switch_2.entry.js +17 -9
- package/dist/esm-es5/mds-input-tip_2.entry.js +3 -3
- package/dist/esm-es5/mds-input-upload.entry.js +2 -2
- package/dist/esm-es5/mds-input.entry.js +30 -25
- package/dist/esm-es5/mds-keyboard-key.entry.js +2 -2
- package/dist/esm-es5/mds-keyboard.entry.js +2 -2
- package/dist/esm-es5/mds-kpi-item.entry.js +2 -2
- package/dist/esm-es5/mds-kpi.entry.js +1 -1
- package/dist/esm-es5/mds-label.entry.js +2 -2
- package/dist/esm-es5/mds-list-item.entry.js +2 -2
- package/dist/esm-es5/mds-list.entry.js +1 -1
- package/dist/esm-es5/mds-mention.entry.js +2 -2
- package/dist/esm-es5/mds-modal.entry.js +5 -5
- package/dist/esm-es5/mds-note.entry.js +2 -2
- package/dist/esm-es5/mds-notification.entry.js +4 -4
- package/dist/esm-es5/mds-paginator-item.entry.js +1 -1
- package/dist/esm-es5/mds-paginator.entry.js +3 -3
- package/dist/esm-es5/mds-policy-ai.entry.js +2 -2
- package/dist/esm-es5/mds-pref-animation.entry.js +2 -2
- package/dist/esm-es5/mds-pref-consumption.entry.js +3 -3
- package/dist/esm-es5/mds-pref-contrast.entry.js +3 -3
- package/dist/esm-es5/mds-pref-language-item.entry.js +1 -1
- package/dist/esm-es5/mds-pref-language.entry.js +2 -2
- package/dist/esm-es5/mds-pref-mode.entry.js +2 -2
- package/dist/esm-es5/mds-pref-theme-item.entry.js +3 -3
- package/dist/esm-es5/mds-pref-theme.entry.js +15 -7
- package/dist/esm-es5/mds-pref.entry.js +14 -5
- package/dist/esm-es5/mds-price-table-features-cell.entry.js +2 -2
- 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 +2 -2
- 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 +3 -3
- package/dist/esm-es5/mds-push-notification-item.entry.js +2 -2
- package/dist/esm-es5/mds-push-notification.entry.js +2 -2
- package/dist/esm-es5/mds-quote.entry.js +2 -2
- package/dist/esm-es5/mds-radial-menu-item.entry.js +2 -2
- package/dist/esm-es5/mds-radial-menu.entry.js +2 -2
- package/dist/esm-es5/mds-separator.entry.js +1 -1
- package/dist/esm-es5/mds-status-bar.entry.js +2 -2
- package/dist/esm-es5/mds-stepper-bar-item.entry.js +3 -3
- package/dist/esm-es5/mds-stepper-bar.entry.js +4 -4
- package/dist/esm-es5/mds-tab-bar-item.entry.js +3 -3
- package/dist/esm-es5/mds-tab-bar.entry.js +1 -1
- package/dist/esm-es5/mds-tab_2.entry.js +14 -4
- 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 +22 -3
- package/dist/esm-es5/mds-table-header.entry.js +2 -2
- package/dist/esm-es5/mds-table-row.entry.js +6 -6
- package/dist/esm-es5/mds-table.entry.js +11 -5
- package/dist/esm-es5/mds-text.entry.js +25 -7
- package/dist/esm-es5/mds-toast.entry.js +2 -2
- package/dist/esm-es5/mds-tooltip.entry.js +8 -3
- package/dist/esm-es5/mds-tree-item.entry.js +2 -2
- package/dist/esm-es5/mds-tree.entry.js +3 -3
- package/dist/esm-es5/mds-url-view.entry.js +2 -2
- package/dist/esm-es5/mds-usage.entry.js +9 -3
- package/dist/esm-es5/mds-video-wall.entry.js +2 -2
- package/dist/esm-es5/mds-zero.entry.js +1 -1
- package/dist/esm-es5/string-6pgPWpGI.js +2 -0
- package/dist/hydrate/index.js +1450 -8261
- package/dist/hydrate/index.mjs +1450 -8261
- package/dist/magma-components/magma-components.esm.js +1 -1
- package/dist/magma-components/p-00ce5c81.entry.js +1 -0
- package/dist/magma-components/{p-2da2cdf3.system.entry.js → p-00ff586a.system.entry.js} +2 -2
- package/dist/magma-components/p-01f05a56.entry.js +1 -0
- package/dist/magma-components/p-0345cbd0.system.entry.js +83 -0
- package/dist/magma-components/p-03a6a8bd.system.entry.js +46 -0
- package/dist/magma-components/p-05de42e1.system.entry.js +1 -0
- package/dist/magma-components/p-063bccb3.entry.js +1 -0
- package/dist/magma-components/{p-f65e29e0.system.entry.js → p-0a38e4ce.system.entry.js} +1 -1
- package/dist/magma-components/p-0c89c485.entry.js +1 -0
- package/dist/magma-components/p-0d94a2b8.entry.js +8 -0
- package/dist/magma-components/{p-f8da21a1.system.entry.js → p-0d97e28d.system.entry.js} +2 -2
- package/dist/magma-components/p-108e31e6.entry.js +1 -0
- package/dist/magma-components/p-114f0bb7.system.entry.js +14 -0
- package/dist/magma-components/{p-dcf841d5.entry.js → p-121730d1.entry.js} +1 -1
- package/dist/magma-components/p-137116df.entry.js +1 -0
- package/dist/magma-components/p-13b0babc.system.entry.js +1 -0
- package/dist/magma-components/p-14a108e8.system.entry.js +8 -0
- package/dist/magma-components/p-14eadf95.system.entry.js +21 -0
- package/dist/magma-components/p-154aff83.entry.js +1 -0
- package/dist/magma-components/p-155f79f4.system.entry.js +47 -0
- package/dist/magma-components/p-17b62839.entry.js +1 -0
- package/dist/magma-components/{p-0d3c3de9.entry.js → p-1802d6a7.entry.js} +1 -1
- package/dist/magma-components/{p-91c4015f.system.entry.js → p-188d9770.system.entry.js} +1 -1
- package/dist/magma-components/p-18ba4766.entry.js +1 -0
- package/dist/magma-components/p-1c63801f.system.entry.js +11 -0
- package/dist/magma-components/p-1c6a507c.system.entry.js +17 -0
- package/dist/magma-components/p-1e2388be.entry.js +1 -0
- package/dist/magma-components/{p-a9e4efa3.entry.js → p-22e9a507.entry.js} +1 -1
- package/dist/magma-components/p-24a9871a.system.entry.js +1 -0
- package/dist/magma-components/p-26332bce.system.entry.js +1 -0
- package/dist/magma-components/p-26c85354.system.entry.js +1 -0
- package/dist/magma-components/p-2708561b.system.entry.js +10 -0
- package/dist/magma-components/{p-ad09a06b.entry.js → p-2710ddc4.entry.js} +1 -1
- package/dist/magma-components/{p-019e8a95.system.entry.js → p-2723caa7.system.entry.js} +2 -2
- package/dist/magma-components/p-294241fa.entry.js +1 -0
- package/dist/magma-components/p-2b2d0910.system.entry.js +1 -0
- package/dist/magma-components/p-2c940d19.entry.js +1 -0
- package/dist/magma-components/p-2de5f5fe.entry.js +1 -0
- package/dist/magma-components/p-2e74231d.system.entry.js +4 -0
- package/dist/magma-components/p-2e83f801.system.entry.js +1 -0
- package/dist/magma-components/{p-771720b7.entry.js → p-2f0815f3.entry.js} +1 -1
- package/dist/magma-components/p-30d36dfe.entry.js +1 -0
- package/dist/magma-components/p-323c7aa4.system.entry.js +25 -0
- package/dist/magma-components/{p-32361702.system.entry.js → p-32e077c0.system.entry.js} +2 -2
- package/dist/magma-components/p-334b305d.system.entry.js +16 -0
- package/dist/magma-components/{p-d93c9a11.system.entry.js → p-341994b3.system.entry.js} +2 -2
- package/dist/magma-components/p-35434d4b.system.entry.js +32 -0
- package/dist/magma-components/p-35ee2d77.entry.js +1 -0
- package/dist/magma-components/p-37495e03.entry.js +1 -0
- package/dist/magma-components/{p-7bea6c05.system.entry.js → p-38e0379a.system.entry.js} +2 -2
- package/dist/magma-components/p-3b91efd1.entry.js +1 -0
- package/dist/magma-components/p-3dc4db04.system.entry.js +16 -0
- package/dist/magma-components/p-3f0e82bc.entry.js +1 -0
- package/dist/magma-components/p-3fa6cf85.system.entry.js +1 -0
- package/dist/magma-components/p-40e97485.entry.js +1 -0
- package/dist/magma-components/p-4159c306.entry.js +1 -0
- package/dist/magma-components/p-42411854.system.entry.js +102 -0
- package/dist/magma-components/{p-fc8f8a0c.entry.js → p-42ebba8c.entry.js} +1 -1
- package/dist/magma-components/p-4356d96e.system.entry.js +21 -0
- package/dist/magma-components/{p-6cbd8a6d.system.entry.js → p-4577948d.system.entry.js} +3 -3
- package/dist/magma-components/p-4658a200.entry.js +1 -0
- package/dist/magma-components/{p-06d9af89.entry.js → p-4cfa925a.entry.js} +1 -1
- package/dist/magma-components/p-4dfeb655.system.entry.js +23 -0
- package/dist/magma-components/p-4ef19542.entry.js +1 -0
- package/dist/magma-components/{p-91451e37.system.entry.js → p-508e10b5.system.entry.js} +2 -2
- package/dist/magma-components/p-514d0fcb.entry.js +1 -0
- package/dist/magma-components/p-522fd3d0.system.entry.js +4 -0
- package/dist/magma-components/p-528d913c.system.entry.js +17 -0
- package/dist/magma-components/p-569cbe13.entry.js +1 -0
- package/dist/magma-components/p-574c2c13.system.entry.js +222 -0
- package/dist/magma-components/{p-876a5fb9.system.entry.js → p-584a4ee8.system.entry.js} +1 -1
- package/dist/magma-components/{p-d7515aae.entry.js → p-595fde64.entry.js} +1 -1
- package/dist/magma-components/p-5989cdf2.system.entry.js +16 -0
- package/dist/magma-components/p-5c17a324.entry.js +1 -0
- package/dist/magma-components/p-5df91427.system.entry.js +15 -0
- package/dist/magma-components/{p-c5ad848f.entry.js → p-5f1132b8.entry.js} +1 -1
- package/dist/magma-components/p-5fcc1455.entry.js +1 -0
- package/dist/magma-components/p-61638aa3.entry.js +1 -0
- package/dist/magma-components/p-634727e6.system.entry.js +22 -0
- package/dist/magma-components/{p-289a874e.entry.js → p-6465c8f4.entry.js} +1 -1
- package/dist/magma-components/{p-7c940015.system.entry.js → p-64f78149.system.entry.js} +1 -1
- package/dist/magma-components/p-6764b13a.entry.js +1 -0
- package/dist/magma-components/p-6812f01b.entry.js +1 -0
- package/dist/magma-components/{p-cd5cf28b.system.entry.js → p-6901428b.system.entry.js} +1 -1
- package/dist/magma-components/p-699a7926.entry.js +1 -0
- package/dist/magma-components/p-69d6cc9e.system.entry.js +7 -0
- package/dist/magma-components/p-6a798061.entry.js +1 -0
- package/dist/magma-components/p-6d350c7c.entry.js +1 -0
- package/dist/magma-components/p-6f5a1248.entry.js +1 -0
- package/dist/magma-components/p-6fba5e6c.entry.js +1 -0
- package/dist/magma-components/p-6fd9a2ae.entry.js +1 -0
- package/dist/magma-components/{p-ff970859.system.entry.js → p-6ff8be3e.system.entry.js} +1 -1
- package/dist/magma-components/p-6pgPWpGI.js +1 -0
- package/dist/magma-components/p-70caf05b.system.entry.js +10 -0
- package/dist/magma-components/{p-2d324edc.entry.js → p-70cc167f.entry.js} +1 -1
- package/dist/magma-components/{p-cc1ee10a.system.entry.js → p-736c0e25.system.entry.js} +2 -2
- package/dist/magma-components/p-73e593a2.system.entry.js +95 -0
- package/dist/magma-components/p-7450a7a7.system.entry.js +49 -0
- package/dist/magma-components/p-7535328a.entry.js +1 -0
- package/dist/magma-components/{p-bd9324f3.system.entry.js → p-76f02296.system.entry.js} +1 -1
- package/dist/magma-components/p-789c1b93.system.entry.js +1 -0
- package/dist/magma-components/p-79bc2e81.entry.js +1 -0
- package/dist/magma-components/p-79dc2243.entry.js +1 -0
- package/dist/magma-components/p-7b1c6eb0.entry.js +1 -0
- package/dist/magma-components/p-7b8b51c8.entry.js +1 -0
- package/dist/magma-components/p-7bc0a6c4.entry.js +1 -0
- package/dist/magma-components/p-7c8e79a7.system.entry.js +4 -0
- package/dist/magma-components/p-7c90298a.entry.js +1 -0
- package/dist/magma-components/p-7e02237b.entry.js +1 -0
- package/dist/magma-components/{p-ef4cd904.system.entry.js → p-7f247e64.system.entry.js} +2 -2
- package/dist/magma-components/p-808f6796.entry.js +1 -0
- package/dist/magma-components/{p-a1b5bd58.entry.js → p-82480df5.entry.js} +1 -1
- package/dist/magma-components/{p-61ff1d85.system.entry.js → p-837fbbf7.system.entry.js} +1 -1
- package/dist/magma-components/p-842b1dfc.entry.js +1 -0
- package/dist/magma-components/p-88c7be3d.system.entry.js +68 -0
- package/dist/magma-components/p-89733d3a.system.entry.js +14 -0
- package/dist/magma-components/p-8c75425d.entry.js +1 -0
- package/dist/magma-components/{p-5ac9e2f4.entry.js → p-8c76410b.entry.js} +1 -1
- package/dist/magma-components/p-8cdad12f.entry.js +1 -0
- package/dist/magma-components/p-8d2a6896.entry.js +1 -0
- package/dist/magma-components/p-8d7835e2.system.entry.js +10 -0
- package/dist/magma-components/p-8f039ca0.system.entry.js +7 -0
- package/dist/magma-components/p-8f54cf62.system.entry.js +4 -0
- package/dist/magma-components/p-8f6bd147.entry.js +1 -0
- package/dist/magma-components/p-9017022c.system.entry.js +15 -0
- package/dist/magma-components/p-909f5b60.system.entry.js +55 -0
- package/dist/magma-components/p-94e9f2be.system.entry.js +11 -0
- package/dist/magma-components/p-976bb373.system.entry.js +90 -0
- package/dist/magma-components/p-97d82884.system.entry.js +16 -0
- package/dist/magma-components/p-97de86c6.system.entry.js +16 -0
- package/dist/magma-components/p-97e9a197.system.entry.js +32 -0
- package/dist/magma-components/p-9a936cae.system.entry.js +45 -0
- package/dist/magma-components/p-9c6d184f.entry.js +1 -0
- package/dist/magma-components/p-9db0a6e9.entry.js +1 -0
- package/dist/magma-components/p-9e662528.entry.js +1 -0
- package/dist/magma-components/{p-7ffda4f5.entry.js → p-9ff02a82.entry.js} +1 -1
- package/dist/magma-components/p-B85MJLTf.js +1 -0
- package/dist/magma-components/p-BJqUjYIG.system.js +1 -0
- package/dist/magma-components/{p-Dg8nxRUX.system.js → p-BcYSdbK0.system.js} +85 -53
- package/dist/magma-components/p-BeYLDgbf.js +1 -0
- package/dist/magma-components/p-D6-Ny6z1.system.js +1 -0
- package/dist/magma-components/{p-BPNsbMrg.system.js → p-DhhAXEdA.system.js} +11 -5
- package/dist/magma-components/p-JMPfVnGv.js +1 -0
- package/dist/magma-components/p-ZDRIVCAt.system.js +1 -1
- package/dist/magma-components/p-a3e3a653.system.entry.js +81 -0
- package/dist/magma-components/p-a41e52f7.entry.js +1 -0
- package/dist/magma-components/{p-dc399372.entry.js → p-a462aadd.entry.js} +1 -1
- package/dist/magma-components/p-a4c26b4d.system.entry.js +19 -0
- package/dist/magma-components/{p-2e01e057.system.entry.js → p-a61c7ae9.system.entry.js} +2 -2
- package/dist/magma-components/p-a653e096.entry.js +1 -0
- package/dist/magma-components/p-a8bf46cb.system.entry.js +1 -0
- package/dist/magma-components/p-a9736d68.system.entry.js +4 -0
- package/dist/magma-components/p-ac4435e7.entry.js +1 -0
- package/dist/magma-components/p-ac873ab4.entry.js +1 -0
- package/dist/magma-components/p-acae292f.system.entry.js +28 -0
- package/dist/magma-components/p-add1a8d0.system.entry.js +7 -0
- package/dist/magma-components/p-b1a0e56e.system.entry.js +42 -0
- package/dist/magma-components/p-b33a6f7e.system.entry.js +13 -0
- package/dist/magma-components/p-b492dd4c.entry.js +1 -0
- package/dist/magma-components/{p-d5e53364.system.entry.js → p-b626c69f.system.entry.js} +1 -1
- package/dist/magma-components/p-b99cac43.entry.js +1 -0
- package/dist/magma-components/p-baf0359b.entry.js +1 -0
- package/dist/magma-components/p-bbd414dc.entry.js +1 -0
- package/dist/magma-components/p-be1aad5f.entry.js +1 -0
- package/dist/magma-components/p-bf05f9f3.entry.js +1 -0
- package/dist/magma-components/p-bf8c6647.system.entry.js +11 -0
- package/dist/magma-components/p-bfe19e4b.entry.js +1 -0
- package/dist/magma-components/p-c1a7266a.entry.js +1 -0
- package/dist/magma-components/{p-a0d9e01f.system.entry.js → p-c34d9e61.system.entry.js} +1 -1
- package/dist/magma-components/p-c3585de7.system.entry.js +7 -0
- package/dist/magma-components/p-c45d9a64.system.entry.js +32 -0
- package/dist/magma-components/p-c4ceaef6.system.entry.js +10 -0
- package/dist/magma-components/{p-c48e3460.entry.js → p-c575cb7b.entry.js} +1 -1
- package/dist/magma-components/p-c644c5fc.system.entry.js +1 -0
- package/dist/magma-components/{p-61bedbe7.system.entry.js → p-c69ec735.system.entry.js} +8 -3
- package/dist/magma-components/p-c7d84d1c.system.entry.js +1 -0
- package/dist/magma-components/p-cb8b45fd.entry.js +1 -0
- package/dist/magma-components/p-cbfd8b10.system.entry.js +16 -0
- package/dist/magma-components/{p-ed897f9f.entry.js → p-ce46191c.entry.js} +1 -1
- package/dist/magma-components/p-cebe7b52.entry.js +1 -0
- package/dist/magma-components/p-cefdc01f.system.entry.js +7 -0
- package/dist/magma-components/{p-f0c67a70.system.entry.js → p-d025a34f.system.entry.js} +2 -2
- package/dist/magma-components/p-d1c47baa.entry.js +1 -0
- package/dist/magma-components/p-d269bfb0.entry.js +1 -0
- package/dist/magma-components/p-d42f267b.system.entry.js +40 -0
- package/dist/magma-components/p-d5bd6bef.entry.js +1 -0
- package/dist/magma-components/p-d65d8a09.system.entry.js +1 -0
- package/dist/magma-components/p-d6eca2ef.entry.js +1 -0
- package/dist/magma-components/p-d716efe9.system.entry.js +1 -0
- package/dist/magma-components/{p-d9fbbf3f.entry.js → p-da6ccc03.entry.js} +1 -1
- package/dist/magma-components/p-dbaf5368.system.entry.js +7 -0
- package/dist/magma-components/p-dc340618.entry.js +1 -0
- package/dist/magma-components/p-dc752e9b.entry.js +1 -0
- package/dist/magma-components/p-e238e2eb.entry.js +1 -0
- package/dist/magma-components/p-e388f1f2.system.entry.js +19 -0
- package/dist/magma-components/p-e50fdcee.entry.js +1 -0
- package/dist/magma-components/p-e779a67f.system.entry.js +10 -0
- package/dist/magma-components/p-e8ae4016.system.entry.js +1 -0
- package/dist/magma-components/{p-9eb1e154.system.entry.js → p-e8d95868.system.entry.js} +2 -2
- package/dist/magma-components/p-ed232c76.entry.js +1 -0
- package/dist/magma-components/{p-f3dbebdd.system.entry.js → p-ed6e287d.system.entry.js} +25 -7
- package/dist/magma-components/p-ed87425c.system.entry.js +13 -0
- package/dist/magma-components/p-ed897125.entry.js +1 -0
- package/dist/magma-components/p-ee876b20.system.entry.js +4 -0
- package/dist/magma-components/p-efe0bb12.system.entry.js +7 -0
- package/dist/magma-components/p-f2412853.system.entry.js +27 -0
- package/dist/magma-components/p-f2743a2b.entry.js +1 -0
- package/dist/magma-components/p-f2f2945b.entry.js +1 -0
- package/dist/magma-components/p-f37f1343.entry.js +1 -0
- package/dist/magma-components/p-f3dd135e.system.entry.js +32 -0
- package/dist/magma-components/{p-3a1a6945.entry.js → p-f5bb8c0c.entry.js} +1 -1
- package/dist/magma-components/p-f5ce24e8.entry.js +1 -0
- package/dist/magma-components/p-f8a88f11.entry.js +1 -0
- package/dist/magma-components/p-f900fe90.entry.js +1 -0
- package/dist/magma-components/{p-eff38775.entry.js → p-faa1f22c.entry.js} +1 -1
- package/dist/magma-components/p-pNJmnrhq.js +1 -0
- package/dist/magma-components/p-pxyGaQ-P.system.js +2 -0
- package/dist/stats.json +2971 -2223
- package/dist/types/common/floating-controller.d.ts +8 -1
- package/dist/types/common/hash.d.ts +8 -0
- package/dist/types/common/string.d.ts +3 -1
- package/dist/types/components/mds-button/mds-button.d.ts +10 -0
- package/dist/types/components/mds-button-dropdown/mds-button-dropdown.d.ts +1 -0
- package/dist/types/components/mds-calendar/mds-calendar.d.ts +1 -0
- package/dist/types/components/mds-file/mds-file.d.ts +6 -1
- package/dist/types/components/mds-filter/mds-filter.d.ts +15 -0
- package/dist/types/components/mds-filter-item/mds-filter-item.d.ts +18 -1
- package/dist/types/components/mds-header-bar/mds-header-bar.d.ts +1 -0
- package/dist/types/components/mds-horizontal-scroll/mds-horizontal-scroll.d.ts +1 -0
- package/dist/types/components/mds-input/mds-input.d.ts +8 -1
- package/dist/types/components/mds-input-date/mds-input-date.d.ts +6 -0
- package/dist/types/components/mds-input-date-range/mds-input-date-range.d.ts +5 -0
- package/dist/types/components/mds-input-select/mds-input-select.d.ts +15 -2
- package/dist/types/components/mds-input-switch/mds-input-switch.d.ts +8 -3
- package/dist/types/components/mds-modal/mds-modal.d.ts +1 -0
- package/dist/types/components/mds-pref/mds-pref.d.ts +5 -8
- package/dist/types/components/mds-pref-theme/mds-pref-theme.d.ts +8 -0
- package/dist/types/components/mds-radial-menu/mds-radial-menu.d.ts +1 -0
- package/dist/types/components/mds-tab/mds-tab.d.ts +8 -0
- package/dist/types/components/mds-table/mds-table.d.ts +8 -1
- package/dist/types/components/mds-table/meta/type.d.ts +1 -0
- package/dist/types/components/mds-table-header-cell/mds-table-header-cell.d.ts +33 -14
- package/dist/types/components/mds-table-header-cell/meta/event-detail.d.ts +6 -0
- package/dist/types/components/mds-text/mds-text.d.ts +8 -4
- package/dist/types/components/mds-tooltip/mds-tooltip.d.ts +8 -1
- package/dist/types/components/mds-usage/mds-usage.d.ts +5 -1
- package/dist/types/components/mds-usage/meta/variants.d.ts +7 -19
- package/dist/types/components.d.ts +123 -18
- package/dist/types/type/floating-ui.d.ts +2 -0
- package/dist/types/type/input.d.ts +3 -0
- package/package.json +15 -15
- package/dist/cjs/_commonjsHelpers-B83fTs8d.js +0 -36
- package/dist/collection/dictionary/icon.js +0 -10
- package/dist/collection/type/icon.js +0 -1
- package/dist/components/p-B3Z2Goa-.js +0 -1
- package/dist/components/p-B3dWp2vS.js +0 -1
- package/dist/components/p-B6FOPjps.js +0 -1
- package/dist/components/p-B7CR1EtF.js +0 -1
- package/dist/components/p-BBPQjm8h.js +0 -1
- package/dist/components/p-BCiJ4PRD.js +0 -1
- package/dist/components/p-BSs0SO-j.js +0 -1
- package/dist/components/p-BTpjOy0A.js +0 -1
- package/dist/components/p-BY6Qu1V4.js +0 -1
- package/dist/components/p-BhmePCyA.js +0 -1
- package/dist/components/p-BpGzrg1C.js +0 -1
- package/dist/components/p-C-J9fW51.js +0 -1
- package/dist/components/p-CAa2kI72.js +0 -1
- package/dist/components/p-CBV19-8O.js +0 -1
- package/dist/components/p-CCv9tBZK.js +0 -1
- package/dist/components/p-CDf607TB.js +0 -1
- package/dist/components/p-CEMAGNly.js +0 -1
- package/dist/components/p-CGYDZBMv.js +0 -1
- package/dist/components/p-CHAGzQT-.js +0 -1
- package/dist/components/p-CHAvkoj3.js +0 -1
- package/dist/components/p-CMFUEkte.js +0 -1
- package/dist/components/p-CR2GGKXK.js +0 -1
- package/dist/components/p-Cb5kuO7B.js +0 -1
- package/dist/components/p-CiNNzAa3.js +0 -1
- package/dist/components/p-DGDdPv_Y.js +0 -1
- package/dist/components/p-D_wD-Pyk.js +0 -1
- package/dist/components/p-E-ZsRS8r.js +0 -1
- package/dist/components/p-HR2JwDjG.js +0 -1
- package/dist/components/p-LE7qQIFR.js +0 -8
- package/dist/components/p-vgIKH234.js +0 -1
- package/dist/esm/_commonjsHelpers-E-ZsRS8r.js +0 -32
- package/dist/esm-es5/_commonjsHelpers-E-ZsRS8r.js +0 -1
- package/dist/magma-components/p-01dd1f55.entry.js +0 -1
- package/dist/magma-components/p-02119624.system.entry.js +0 -40
- package/dist/magma-components/p-02fc7592.entry.js +0 -1
- package/dist/magma-components/p-03cd0069.system.entry.js +0 -1
- package/dist/magma-components/p-05fbca60.system.entry.js +0 -37
- package/dist/magma-components/p-07e4701d.entry.js +0 -1
- package/dist/magma-components/p-081a19b1.system.entry.js +0 -45
- package/dist/magma-components/p-09d0b6a8.entry.js +0 -1
- package/dist/magma-components/p-0b300de7.entry.js +0 -1
- package/dist/magma-components/p-1150ffb8.system.entry.js +0 -10
- package/dist/magma-components/p-115a5e47.entry.js +0 -1
- package/dist/magma-components/p-1314d80e.entry.js +0 -1
- package/dist/magma-components/p-133a6ffd.system.entry.js +0 -49
- package/dist/magma-components/p-13db55de.entry.js +0 -1
- package/dist/magma-components/p-1a2731ec.system.entry.js +0 -10
- package/dist/magma-components/p-1a602906.system.entry.js +0 -13
- package/dist/magma-components/p-1c975156.entry.js +0 -1
- package/dist/magma-components/p-1d154234.system.entry.js +0 -12
- package/dist/magma-components/p-1d9d7666.entry.js +0 -1
- package/dist/magma-components/p-1ddaaa6d.system.entry.js +0 -217
- package/dist/magma-components/p-21aa0a74.entry.js +0 -1
- package/dist/magma-components/p-21c46e74.system.entry.js +0 -4
- package/dist/magma-components/p-2399b7e8.entry.js +0 -1
- package/dist/magma-components/p-25407d89.entry.js +0 -1
- package/dist/magma-components/p-27547a7a.system.entry.js +0 -7
- package/dist/magma-components/p-2be3bd23.system.entry.js +0 -1
- package/dist/magma-components/p-2c586431.entry.js +0 -1
- package/dist/magma-components/p-2e9b80e8.entry.js +0 -1
- package/dist/magma-components/p-30c3872d.entry.js +0 -1
- package/dist/magma-components/p-3231a6a3.entry.js +0 -1
- package/dist/magma-components/p-3448d0ce.entry.js +0 -1
- package/dist/magma-components/p-367cee40.system.entry.js +0 -1
- package/dist/magma-components/p-3a8870e4.system.entry.js +0 -47
- package/dist/magma-components/p-3b68fbcd.system.entry.js +0 -22
- package/dist/magma-components/p-3ecade3c.system.entry.js +0 -11
- package/dist/magma-components/p-3f05ec8a.entry.js +0 -1
- package/dist/magma-components/p-4073c5f2.system.entry.js +0 -90
- package/dist/magma-components/p-40bd2e6d.entry.js +0 -1
- package/dist/magma-components/p-423597db.system.entry.js +0 -4
- package/dist/magma-components/p-443c2a29.system.entry.js +0 -10
- package/dist/magma-components/p-45a91f1c.system.entry.js +0 -1
- package/dist/magma-components/p-487af9d3.entry.js +0 -1
- package/dist/magma-components/p-4909070e.entry.js +0 -1
- package/dist/magma-components/p-4d966161.system.entry.js +0 -14
- package/dist/magma-components/p-4ddf891e.system.entry.js +0 -69
- package/dist/magma-components/p-4e15cde7.entry.js +0 -1
- package/dist/magma-components/p-4f14a166.entry.js +0 -1
- package/dist/magma-components/p-4ffec31a.system.entry.js +0 -1
- package/dist/magma-components/p-50b266e9.system.entry.js +0 -4
- package/dist/magma-components/p-5165b09f.system.entry.js +0 -4
- package/dist/magma-components/p-544cc9c7.system.entry.js +0 -25
- package/dist/magma-components/p-562bb482.system.entry.js +0 -16
- package/dist/magma-components/p-5ae5ec95.entry.js +0 -1
- package/dist/magma-components/p-5d2d8ffe.system.entry.js +0 -11
- package/dist/magma-components/p-5e180f53.system.entry.js +0 -32
- package/dist/magma-components/p-62b17608.system.entry.js +0 -102
- package/dist/magma-components/p-63e7c98f.entry.js +0 -1
- package/dist/magma-components/p-6474c850.entry.js +0 -8
- package/dist/magma-components/p-660657ac.system.entry.js +0 -15
- package/dist/magma-components/p-66237a64.entry.js +0 -1
- package/dist/magma-components/p-6702e489.entry.js +0 -1
- package/dist/magma-components/p-694ed534.entry.js +0 -1
- package/dist/magma-components/p-6b446fd9.system.entry.js +0 -81
- package/dist/magma-components/p-6c414bc2.system.entry.js +0 -19
- package/dist/magma-components/p-6d0dc1fd.entry.js +0 -1
- package/dist/magma-components/p-6ed05d99.entry.js +0 -1
- package/dist/magma-components/p-6f2471b1.entry.js +0 -1
- package/dist/magma-components/p-6fa03aab.system.entry.js +0 -7
- package/dist/magma-components/p-70141ccd.entry.js +0 -1
- package/dist/magma-components/p-707d8626.system.entry.js +0 -2838
- package/dist/magma-components/p-71dafc3f.entry.js +0 -1
- package/dist/magma-components/p-726209f4.system.entry.js +0 -1
- package/dist/magma-components/p-745ee76b.system.entry.js +0 -32
- package/dist/magma-components/p-761415b3.system.entry.js +0 -37
- package/dist/magma-components/p-7a7c308b.entry.js +0 -1
- package/dist/magma-components/p-7ca990d4.system.entry.js +0 -11
- package/dist/magma-components/p-7d6ca97d.system.entry.js +0 -7
- package/dist/magma-components/p-8097dfc8.system.entry.js +0 -7
- package/dist/magma-components/p-809adece.system.entry.js +0 -17
- package/dist/magma-components/p-843ab1b4.entry.js +0 -1
- package/dist/magma-components/p-87026d34.entry.js +0 -1
- package/dist/magma-components/p-8765dc11.entry.js +0 -1
- package/dist/magma-components/p-87faaa8e.system.entry.js +0 -16
- package/dist/magma-components/p-8a838a1a.entry.js +0 -1
- package/dist/magma-components/p-8bcb2a5f.entry.js +0 -1
- package/dist/magma-components/p-8c93550d.entry.js +0 -1
- package/dist/magma-components/p-8ca1d30d.system.entry.js +0 -1
- package/dist/magma-components/p-91c8960a.system.entry.js +0 -1
- package/dist/magma-components/p-932620b6.entry.js +0 -1
- package/dist/magma-components/p-939da879.system.entry.js +0 -8
- package/dist/magma-components/p-97bde480.entry.js +0 -1
- package/dist/magma-components/p-97d02403.entry.js +0 -1
- package/dist/magma-components/p-983f3e40.entry.js +0 -1
- package/dist/magma-components/p-99227c78.system.entry.js +0 -11
- package/dist/magma-components/p-9a583f6b.system.entry.js +0 -1
- package/dist/magma-components/p-9a86e0ce.system.entry.js +0 -1
- package/dist/magma-components/p-9d1cdb42.system.entry.js +0 -15
- package/dist/magma-components/p-9e5982b6.entry.js +0 -1
- package/dist/magma-components/p-9eef2f79.entry.js +0 -1
- package/dist/magma-components/p-9fe14430.system.entry.js +0 -7
- package/dist/magma-components/p-9fe7035a.entry.js +0 -1
- package/dist/magma-components/p-BpVYIPkx.js +0 -1
- package/dist/magma-components/p-CHAGzQT-.js +0 -1
- package/dist/magma-components/p-DIUTGDX_.system.js +0 -1
- package/dist/magma-components/p-E-ZsRS8r.js +0 -1
- package/dist/magma-components/p-a0972ec9.entry.js +0 -1
- package/dist/magma-components/p-a1851e6f.entry.js +0 -1
- package/dist/magma-components/p-a2d9549d.system.entry.js +0 -32
- package/dist/magma-components/p-a5a13b20.entry.js +0 -1
- package/dist/magma-components/p-a6a71c77.entry.js +0 -1
- package/dist/magma-components/p-a96312c1.entry.js +0 -1
- package/dist/magma-components/p-aa0bd826.entry.js +0 -1
- package/dist/magma-components/p-aa74169f.system.entry.js +0 -1
- package/dist/magma-components/p-ab4ffbd4.system.entry.js +0 -68
- package/dist/magma-components/p-ad9cb1f5.entry.js +0 -1
- package/dist/magma-components/p-aed8b119.entry.js +0 -1
- package/dist/magma-components/p-afbef2fc.entry.js +0 -1
- package/dist/magma-components/p-b183d698.system.entry.js +0 -16
- package/dist/magma-components/p-b49196da.entry.js +0 -1
- package/dist/magma-components/p-b77a2832.entry.js +0 -1
- package/dist/magma-components/p-b925c109.system.entry.js +0 -14
- package/dist/magma-components/p-b9e3281a.system.entry.js +0 -72
- package/dist/magma-components/p-bb0538b6.entry.js +0 -1
- package/dist/magma-components/p-bb055583.entry.js +0 -1
- package/dist/magma-components/p-bc6a41a9.system.entry.js +0 -1
- package/dist/magma-components/p-c4beed1b.entry.js +0 -1
- package/dist/magma-components/p-c4ccb710.entry.js +0 -1
- package/dist/magma-components/p-c4e4ba90.system.entry.js +0 -38
- package/dist/magma-components/p-c573e136.entry.js +0 -1
- package/dist/magma-components/p-c6841b21.entry.js +0 -1
- package/dist/magma-components/p-c89a44b2.entry.js +0 -1
- package/dist/magma-components/p-c94575de.entry.js +0 -1
- package/dist/magma-components/p-cabe9133.system.entry.js +0 -4
- package/dist/magma-components/p-cb2c5f1b.entry.js +0 -1
- package/dist/magma-components/p-cb571b55.system.entry.js +0 -1
- package/dist/magma-components/p-cbc0f01f.system.entry.js +0 -17
- package/dist/magma-components/p-cd1dc29a.entry.js +0 -1
- package/dist/magma-components/p-cd952369.entry.js +0 -1
- package/dist/magma-components/p-d35aebe5.entry.js +0 -1
- package/dist/magma-components/p-d74fa7af.entry.js +0 -1
- package/dist/magma-components/p-d7a94afb.system.entry.js +0 -7
- package/dist/magma-components/p-db492cf5.system.entry.js +0 -13
- package/dist/magma-components/p-dc06b29e.entry.js +0 -1
- package/dist/magma-components/p-dc7bada4.entry.js +0 -1
- package/dist/magma-components/p-dfb4a965.system.entry.js +0 -28
- package/dist/magma-components/p-e1a91e9e.system.entry.js +0 -1
- package/dist/magma-components/p-e5438280.system.entry.js +0 -10
- package/dist/magma-components/p-e8cd2b93.system.entry.js +0 -4
- package/dist/magma-components/p-e95f2a48.entry.js +0 -1
- package/dist/magma-components/p-eb113725.system.entry.js +0 -1
- package/dist/magma-components/p-ec5eccbb.entry.js +0 -1
- package/dist/magma-components/p-eca99a0a.system.entry.js +0 -1
- package/dist/magma-components/p-eea815ca.system.entry.js +0 -16
- package/dist/magma-components/p-eff1fd6c.system.entry.js +0 -15
- package/dist/magma-components/p-f01874a8.entry.js +0 -1
- package/dist/magma-components/p-f05d7005.entry.js +0 -1
- package/dist/magma-components/p-f215496c.entry.js +0 -1
- package/dist/magma-components/p-f28cfb33.system.entry.js +0 -4
- package/dist/magma-components/p-f830793e.entry.js +0 -1
- package/dist/magma-components/p-f835c307.system.entry.js +0 -7
- package/dist/magma-components/p-f89c3a01.system.entry.js +0 -32
- package/dist/magma-components/p-f8eb19b3.entry.js +0 -1
- package/dist/magma-components/p-f8feee93.system.entry.js +0 -4
- package/dist/magma-components/p-f97b4ff4.system.entry.js +0 -16
- package/dist/magma-components/p-fcaa5967.entry.js +0 -18
- package/dist/types/dictionary/icon.d.ts +0 -4
- package/dist/types/type/icon.d.ts +0 -1
package/dist/documentation.json
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{
|
|
2
|
-
"timestamp": "2026-10-
|
|
2
|
+
"timestamp": "2026-10-15T16:08:09",
|
|
3
3
|
"compiler": {
|
|
4
4
|
"name": "@stencil/core",
|
|
5
5
|
"version": "4.44.2",
|
|
@@ -1002,8 +1002,8 @@
|
|
|
1002
1002
|
"filePath": "src/components/mds-author/mds-author.tsx",
|
|
1003
1003
|
"encapsulation": "shadow",
|
|
1004
1004
|
"tag": "mds-author",
|
|
1005
|
-
"readme": "# mds-author\n\n\n
|
|
1006
|
-
"docs": "",
|
|
1005
|
+
"readme": "# mds-author\n\n\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
|
|
1006
|
+
"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.",
|
|
1007
1007
|
"docsTags": [
|
|
1008
1008
|
{
|
|
1009
1009
|
"name": "slot",
|
|
@@ -1044,8 +1044,8 @@
|
|
|
1044
1044
|
"filePath": "src/components/mds-avatar/mds-avatar.tsx",
|
|
1045
1045
|
"encapsulation": "shadow",
|
|
1046
1046
|
"tag": "mds-avatar",
|
|
1047
|
-
"readme": "# mds-avatar\n\n
|
|
1048
|
-
"docs": "
|
|
1047
|
+
"readme": "# mds-avatar\n\n\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
|
|
1048
|
+
"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.",
|
|
1049
1049
|
"docsTags": [
|
|
1050
1050
|
{
|
|
1051
1051
|
"name": "part",
|
|
@@ -2870,8 +2870,8 @@
|
|
|
2870
2870
|
"filePath": "src/components/mds-bibliography/mds-bibliography.tsx",
|
|
2871
2871
|
"encapsulation": "shadow",
|
|
2872
2872
|
"tag": "mds-bibliography",
|
|
2873
|
-
"readme": "# mds-bibliography\n\n
|
|
2874
|
-
"docs": "
|
|
2873
|
+
"readme": "# mds-bibliography\n\n\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
|
|
2874
|
+
"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.",
|
|
2875
2875
|
"docsTags": [],
|
|
2876
2876
|
"usage": {
|
|
2877
2877
|
"1. Description": "The `<mds-bibliography>` web component renders a single citation entry formatted according to a recognized academic style. It is a presentational component that takes structured metadata (author, title, publisher, date, location, URL) and composes it into a styled, correctly-punctuated reference line, replacing the manual assembly of a bibliography string.\n\n#### Semantic Behavior\n\n- **Citation formatting**: The `format` prop drives the entire output - field ordering, punctuation, separators, author-name abbreviation, and date layout. Switching formats re-composes the same metadata rather than just restyling it.\n- **Author parsing**: `author` is parsed, not displayed verbatim. Names are split on commas into multiple authors, first/last names are detected by position (first name first: `Mario Rossi`; the parser does not trim, so put no space after a comma that precedes an unquoted name), and composite first or last names can be grouped with single or double quotation marks (e.g. `'Jhon Arthur' Doe`). Each author is then abbreviated per the active format (APA initials, MLA full first name).\n- **Date handling**: `date` accepts an ISO string or a numeric timestamp and renders inside a semantic `<time>` element; an invalid date renders as an empty date (APA keeps empty parentheses), and month names are localized in Italian.\n- **Link vs. plain title**: When both `name` and `url` are set, the title renders as a link (`target=\"_blank\"`) carrying the `rel` value; otherwise it renders as plain emphasized text.\n- **No slots**: Content is built entirely from props; the component does not project slotted children.\n\n#### Properties & Visual Configurations\n\n- **`format`** selects the citation standard (`'apa'`, `'mla'`, `'turabian'`) and is the primary behavioral switch; pick it to match the referencing convention required by the document. APA puts the date in parentheses right after the authors, MLA/Turabian place the date at the end, and each applies its own punctuation between location, publisher, and date.\n- **`rel`** sets the relationship attribute applied to the generated title link (`'external'` or `'author'`); it only takes effect when the title is rendered as a hyperlink.\n\n#### Other behavioral props\n\n- **`typography`** and **`variant`** set the text role and styling of the rendered citation; they affect appearance only, not the citation structure.\n",
|
|
@@ -3566,7 +3566,7 @@
|
|
|
3566
3566
|
"filePath": "src/components/mds-button/mds-button.tsx",
|
|
3567
3567
|
"encapsulation": "shadow",
|
|
3568
3568
|
"tag": "mds-button",
|
|
3569
|
-
"readme": "# mds-button\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
|
|
3569
|
+
"readme": "# mds-button\n\n\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
|
|
3570
3570
|
"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.",
|
|
3571
3571
|
"docsTags": [
|
|
3572
3572
|
{
|
|
@@ -3583,9 +3583,9 @@
|
|
|
3583
3583
|
}
|
|
3584
3584
|
],
|
|
3585
3585
|
"usage": {
|
|
3586
|
-
"1. Description": "The `<mds-button>` web component is the primary interactive action control of the Magma Design System. It renders as a button, or as a link when `href` is set, handling form association, accessibility, loading state, and iconography natively.\n\n#### Semantic Behavior\n\n- **Button vs. link**: Providing `href` renders a real anchor inside the component and gives the host `role=\"link\"`. The browser follows the link, so a modifier or middle click opens it in a new tab and the context menu offers the link actions; `target=\"blank\"` opens a new tab on a plain click too. A `click` listener on the host cancels the navigation with `preventDefault()`, which is how a client-side router takes over. A click from the keyboard, a script or an assistive technology lands on the host and is followed the same way, unless cancelled.\n- **Form association**: Inside a `<form>` the component submits (`type=\"submit\"`, default) or resets (`type=\"reset\"`) it like a native button, with no extra wiring; use `type=\"button\"` to opt out. With `name` set, a submit sends `name=value`, so buttons that submit the same form tell the receiver which one was chosen. A custom element cannot be a submitter, so `event.submitter` is a hidden native button that stands in for the component: it carries the same `name` and `value`, but it is not the `mds-button` element.\n- **Active state**: Mirrors a visual pressed state through the `active` attribute, safe to drive from CSS attribute selectors.\n- **Disabled state**: Blocks pointer and keyboard activation and removes the host from the tab sequence. A disabled `<fieldset>` around the button disables it the same way, as it does a native button, without setting `disabled`.\n- **Await state**: Renders an inline spinner, blocks pointer activation, and sets `aria-busy=\"true\"` for assistive tech. Remove the attribute when done - do not set `await=\"false\"`.\n- **Accessibility**: Sets `role=\"button\"` on the host, `role=\"link\"` when `href` is set; the `label` prop (or slotted text) is rendered as the button text, which names it. Without a label,
|
|
3587
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-button>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Text Button via `label` Prop\n\nThe canonical form. Use the `label` prop for the button's text; it is rendered inside the button and is its accessible name, so screen readers work without extra wiring.\n\n```html\n<mds-button label=\"Conferma azione\" variant=\"primary\" tone=\"strong\"></mds-button>\n```\n\n#### Variant and Tone for Emphasis\n\nPair the same `variant` with a different `tone` to express importance. Do not invent custom colors to dim or saturate.\n\n```html\n<!-- High emphasis: primary call to action -->\n<mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n\n<!-- Medium emphasis: supporting action -->\n<mds-button label=\"Modifica\" variant=\"primary\" tone=\"outline\"></mds-button>\n\n<!-- Low emphasis: in-text or destructive secondary action -->\n<mds-button label=\"Annulla\" variant=\"error\" tone=\"text\"></mds-button>\n```\n\n#### Sizing\n\nUse the `size` prop. Do not override dimensions with inline `width` / `height`.\n\n```html\n<mds-button label=\"Small\" size=\"sm\" variant=\"primary\"></mds-button>\n<mds-button label=\"Medium\" size=\"md\" variant=\"primary\"></mds-button>\n<mds-button label=\"Large\" size=\"lg\" variant=\"primary\"></mds-button>\n<mds-button label=\"Extra large\" size=\"xl\" variant=\"primary\"></mds-button>\n```\n\n#### Button with Icon\n\nReference icons by their filename slug (no `.svg` extension). `icon-position` defaults to `left`; set it to `right` for forward-motion CTAs.\n\n```html\n<!-- Left icon (default) -->\n<mds-button label=\"Aggiungi\" icon=\"mi/baseline/add\" variant=\"primary\" tone=\"weak\"></mds-button>\n\n<!-- Right icon -->\n<mds-button\n label=\"Avanti\"\n icon=\"mi/baseline/arrow-forward\"\n icon-position=\"right\"\n variant=\"primary\"\n></mds-button>\n```\n\n#### Icon-Only Button\n\nOmit `label` and provide `aria-label` (or `title`) explicitly. Without one, the component names the button after the last segment of the icon slug (\"delete\"), which names the icon, not the action.\n\n```html\n<mds-button\n icon=\"mi/baseline/delete\"\n aria-label=\"Elimina elemento\"\n variant=\"error\"\n tone=\"text\"\n></mds-button>\n```\n\n#### Hyperlink via `href`\n\nSetting `href` renders a real link: the browser follows it, in a new tab on a modifier or middle click, and the context menu offers the link actions. Use `target=\"blank\"` to open in a new tab on a plain click too; default is `self`.\n\n```html\n<mds-button\n label=\"Visita il sito\"\n href=\"https://example.com\"\n target=\"blank\"\n variant=\"primary\"\n tone=\"outline\"\n></mds-button>\n```\n\n#### Client-Side Routing via `href`\n\nIn a single-page app keep `href` for the link it gives (new tab, context menu, crawlers) and register the router once with `NavigationService`, from `@maggioli-design-system/magma/services`: every component link is then routed on the client on a plain click, with no listener per button. A modifier or middle click, `target=\"blank\"` and a link to another origin stay with the browser; return `false` from the handler for a link the browser is to load.\n\n```html\n<mds-button label=\"Pratiche\" href=\"/pratiche\" variant=\"primary\" tone=\"text\"></mds-button>\n\n<script type=\"module\">\n import { NavigationService } from '@maggioli-design-system/magma/services';\n\n NavigationService.setHandler((href) => router.navigate(href));\n</script>\n```\n\nWithout a registered router, cancel the click on the button and route by hand: the component honours `preventDefault()`. Leave a modifier click alone, so that the browser opens the link in a new tab.\n\n```html\n<script>\n document.querySelector('mds-button[href]').addEventListener('click', (event) => {\n if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;\n event.preventDefault();\n router.navigate(event.currentTarget.href);\n });\n</script>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while a request is in flight. The component renders an inline spinner, blocks pointer activation, and sets `aria-busy=\"true\"`. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-button label=\"Salvataggio in corso...\" await variant=\"primary\"></mds-button>\n```\n\n#### Form Participation\n\n`<mds-button>` is form-associated. Inside a `<form>` it natively triggers submit (`type=\"submit\"`, default) or reset (`type=\"reset\"`). Use `type=\"button\"` for any action that must not submit the form.\n\n```html\n<form action=\"/save\" method=\"post\">\n <mds-input-field label=\"Titolo\">\n <mds-input name=\"title\"></mds-input>\n </mds-input-field>\n\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Reimposta\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button type=\"button\" label=\"Anteprima\" variant=\"primary\" tone=\"text\"></mds-button>\n</form>\n```\n\n#### Several Actions That Submit One Form\n\nGive the buttons the same `name` and a different `value`, as with native submit buttons: the receiver reads which action was chosen from `name`.\n\n```html\n<form action=\"/mail\" method=\"post\">\n <mds-input-field label=\"Oggetto\">\n <mds-input name=\"subject\"></mds-input>\n </mds-input-field>\n\n <!-- the receiver gets action=send or action=draft -->\n <mds-button name=\"action\" value=\"send\" label=\"Invia\" variant=\"primary\"></mds-button>\n <mds-button name=\"action\" value=\"draft\" label=\"Salva come bozza\" tone=\"outline\"></mds-button>\n</form>\n```\n\nWhen your code handles the submit, build the form data with `event.submitter`, as for a native button: it carries the `name` / `value` of the button that was clicked.\n\n```js\nform.addEventListener('submit', (event) => {\n event.preventDefault();\n const data = new FormData(form, event.submitter);\n data.get('action'); // 'send' or 'draft'\n});\n```\n\nTo show one action and keep the others in a menu, use [`mds-button-dropdown`](../mds-button-dropdown/AGENTS.md) with `type=\"submit\"`: its primary action and its menu items send `name` / `value` the same way.\n\n#### Notification Badge via Named Slot\n\nThe `notification` slot accepts an `<mds-notification>`. This is the documented exception to the default-slot-is-text rule.\n\n```html\n<mds-button label=\"Notifiche\" icon=\"mi/baseline/notifications\" variant=\"primary\" tone=\"weak\">\n <mds-notification slot=\"notification\" value=\"12\"></mds-notification>\n</mds-button>\n```\n\n#### SSO Identity Variants\n\n`variant=\"google\"` and `variant=\"apple\"` apply the brand-correct chrome for SSO entry points. Do not reuse them for non-SSO buttons.\n\n```html\n<mds-button label=\"Accedi con Google\" variant=\"google\"></mds-button>\n<mds-button label=\"Accedi con Apple\" variant=\"apple\"></mds-button>\n```\n\n#### Styling Customization\n\nStyle the button only through its documented `--mds-button-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode, named themes and high contrast keep working.\n\n```css\n.featured-action mds-button {\n --mds-button-background: rgb(var(--magma-accent-emphasis));\n --mds-button-color: rgb(var(--magma-accent-on-emphasis));\n --mds-button-radius: var(--magma-radius-lg);\n --mds-button-gap: calc(var(--spacing) * 300);\n}\n```\n",
|
|
3588
|
-
"3. Antipattern": "Common incorrect uses of `<mds-button>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Put HTML in the Default Slot\n\nThe default slot accepts plain text only; nested elements are stripped or break layout. Use the `label` prop for text and the dedicated props/slots for everything else.\n\n```html\n<!-- INCORRECT -->\n<mds-button>\n <span class=\"bold\">Scarica</span>\n <small>(PDF)</small>\n</mds-button>\n\n<!-- CORRECT -->\n<mds-button label=\"Scarica (PDF)\" icon=\"mi/baseline/download\" variant=\"primary\"></mds-button>\n```\n\n#### Do Not Nest `<mds-button>` Inside an Anchor\n\nWrapping the button in `<a>` creates nested interactive controls, breaks keyboard semantics, and fails accessibility audits. Use the `href` prop on the component instead - it renders the link itself.\n\n```html\n<!-- INCORRECT -->\n<a href=\"/login\">\n <mds-button label=\"Accedi\"></mds-button>\n</a>\n\n<!-- CORRECT -->\n<mds-button label=\"Accedi\" href=\"/login\"></mds-button>\n```\n\n#### Do Not Follow the `href` Yourself in a Click Listener\n\nWith `href` set the component already renders a link the browser follows. Assigning `window.location` in a click listener loads the page a second time and takes a modifier click, which the browser would open in a new tab, into the current one. Either let the browser follow the link, or cancel the click and route on the client.\n\n```js\n// INCORRECT\nbutton.addEventListener('click', () => {\n window.location.href = button.href;\n});\n\n// CORRECT: a client-side router cancels the click and routes\nbutton.addEventListener('click', (event) => {\n if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;\n event.preventDefault();\n router.navigate(button.href);\n});\n```\n\n#### Icon-Only Buttons Without an Accessible Name\n\nWhen `label` is empty, the component derives
|
|
3586
|
+
"1. Description": "The `<mds-button>` web component is the primary interactive action control of the Magma Design System. It renders as a button, or as a link when `href` is set, handling form association, accessibility, loading state, and iconography natively.\n\n#### Semantic Behavior\n\n- **Button vs. link**: Providing `href` renders a real anchor inside the component and gives the host `role=\"link\"`. The browser follows the link, so a modifier or middle click opens it in a new tab and the context menu offers the link actions; `target=\"blank\"` opens a new tab on a plain click too. A `click` listener on the host cancels the navigation with `preventDefault()`, which is how a client-side router takes over. A click from the keyboard, a script or an assistive technology lands on the host and is followed the same way, unless cancelled.\n- **Form association**: Inside a `<form>` the component submits (`type=\"submit\"`, default) or resets (`type=\"reset\"`) it like a native button, with no extra wiring; use `type=\"button\"` to opt out. With `name` set, a submit sends `name=value`, so buttons that submit the same form tell the receiver which one was chosen. A custom element cannot be a submitter, so `event.submitter` is a hidden native button that stands in for the component: it carries the same `name` and `value`, but it is not the `mds-button` element.\n- **Active state**: Mirrors a visual pressed state through the `active` attribute, safe to drive from CSS attribute selectors.\n- **Disabled state**: Blocks pointer and keyboard activation and removes the host from the tab sequence. A disabled `<fieldset>` around the button disables it the same way, as it does a native button, without setting `disabled`.\n- **Await state**: Renders an inline spinner, blocks pointer activation, and sets `aria-busy=\"true\"` for assistive tech. Remove the attribute when done - do not set `await=\"false\"`.\n- **Accessibility**: Sets `role=\"button\"` on the host, `role=\"link\"` when `href` is set, whatever the format of the icon; the `label` prop (or slotted text) is rendered as the button text, which names it. Without a label, an `aria-label` or a `title`, the component sets `title` from the last segment of the icon slug (`mi/baseline/delete` -> \"delete\"), which names the icon, not the action; an icon given as inline SVG or base64 has no slug, and leaves the button with no name at all: icon-only buttons need an explicit `aria-label` (or `title`), or an `mds-tooltip` with `relation=\"label\"`. A host with `aria-labelledby` gets no name from the slug, and loses the one it had when the attribute comes later, as it does from the tooltip.\n- **Sizing**: The `size` prop drives padding, font size, and minimum hit area. Do not override dimensions with inline `width` / `height`.\n- **Linking constraint**: `target` is effective only when `href` is set.\n\n#### Component-specific variants and tones\n\nThe shared `variant` / `tone` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md). `<mds-button>` adds:\n\n- **`variant=\"google\"` / `variant=\"apple\"`**: brand-correct chrome for SSO entry points. Do not reuse them for non-SSO buttons.\n- **`tone=\"box\"`**: the `strong` fill with an embossed, raised shadow (`--shadow-box-solid-strong`) and a brighter hover: more marked than `strong`, not less.\n\n#### Other behavioral props\n\n- **`icon`** is an SVG filename slug from the Magma icon library; **`iconPosition`** places the glyph relative to the label (use `right` for forward-motion CTAs).\n- **`truncate`**: `word` (default) keeps the label on one line and cuts it with an ellipsis, `all` clamps it with `line-clamp` (one line in the button), `none` lets it wrap onto more lines.\n- **`animation`**: `yugop` progressively reveals characters; otherwise text renders immediately.\n",
|
|
3587
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-button>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Text Button via `label` Prop\n\nThe canonical form. Use the `label` prop for the button's text; it is rendered inside the button and is its accessible name, so screen readers work without extra wiring.\n\n```html\n<mds-button label=\"Conferma azione\" variant=\"primary\" tone=\"strong\"></mds-button>\n```\n\n#### Variant and Tone for Emphasis\n\nPair the same `variant` with a different `tone` to express importance. Do not invent custom colors to dim or saturate.\n\n```html\n<!-- High emphasis: primary call to action -->\n<mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n\n<!-- Medium emphasis: supporting action -->\n<mds-button label=\"Modifica\" variant=\"primary\" tone=\"outline\"></mds-button>\n\n<!-- Low emphasis: in-text or destructive secondary action -->\n<mds-button label=\"Annulla\" variant=\"error\" tone=\"text\"></mds-button>\n```\n\n#### Sizing\n\nUse the `size` prop. Do not override dimensions with inline `width` / `height`.\n\n```html\n<mds-button label=\"Small\" size=\"sm\" variant=\"primary\"></mds-button>\n<mds-button label=\"Medium\" size=\"md\" variant=\"primary\"></mds-button>\n<mds-button label=\"Large\" size=\"lg\" variant=\"primary\"></mds-button>\n<mds-button label=\"Extra large\" size=\"xl\" variant=\"primary\"></mds-button>\n```\n\n#### Button with Icon\n\nReference icons by their filename slug (no `.svg` extension). `icon-position` defaults to `left`; set it to `right` for forward-motion CTAs.\n\n```html\n<!-- Left icon (default) -->\n<mds-button label=\"Aggiungi\" icon=\"mi/baseline/add\" variant=\"primary\" tone=\"weak\"></mds-button>\n\n<!-- Right icon -->\n<mds-button\n label=\"Avanti\"\n icon=\"mi/baseline/arrow-forward\"\n icon-position=\"right\"\n variant=\"primary\"\n></mds-button>\n```\n\n#### Icon-Only Button\n\nOmit `label` and provide `aria-label` (or `title`) explicitly. Without one, the component names the button after the last segment of the icon slug (\"delete\"), which names the icon, not the action.\n\n```html\n<mds-button\n icon=\"mi/baseline/delete\"\n aria-label=\"Elimina elemento\"\n variant=\"error\"\n tone=\"text\"\n></mds-button>\n```\n\nWhen an `mds-tooltip` shows the name of the button, let the tooltip be the name with `relation=\"label\"` instead: the button then needs no `aria-label`, and gets no `title` from the icon slug.\n\n```html\n<mds-button id=\"elimina-btn\" icon=\"mi/baseline/delete\" variant=\"error\" tone=\"text\"></mds-button>\n<mds-tooltip target=\"#elimina-btn\" relation=\"label\">Elimina elemento</mds-tooltip>\n```\n\n#### Hyperlink via `href`\n\nSetting `href` renders a real link: the browser follows it, in a new tab on a modifier or middle click, and the context menu offers the link actions. Use `target=\"blank\"` to open in a new tab on a plain click too; default is `self`.\n\n```html\n<mds-button\n label=\"Visita il sito\"\n href=\"https://example.com\"\n target=\"blank\"\n variant=\"primary\"\n tone=\"outline\"\n></mds-button>\n```\n\n#### Client-Side Routing via `href`\n\nIn a single-page app keep `href` for the link it gives (new tab, context menu, crawlers) and register the router once with `NavigationService`, from `@maggioli-design-system/magma/services`: every component link is then routed on the client on a plain click, with no listener per button. A modifier or middle click, `target=\"blank\"` and a link to another origin stay with the browser; return `false` from the handler for a link the browser is to load.\n\n```html\n<mds-button label=\"Pratiche\" href=\"/pratiche\" variant=\"primary\" tone=\"text\"></mds-button>\n\n<script type=\"module\">\n import { NavigationService } from '@maggioli-design-system/magma/services';\n\n NavigationService.setHandler((href) => router.navigate(href));\n</script>\n```\n\nWithout a registered router, cancel the click on the button and route by hand: the component honours `preventDefault()`. Leave a modifier click alone, so that the browser opens the link in a new tab.\n\n```html\n<script>\n document.querySelector('mds-button[href]').addEventListener('click', (event) => {\n if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;\n event.preventDefault();\n router.navigate(event.currentTarget.href);\n });\n</script>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while a request is in flight. The component renders an inline spinner, blocks pointer activation, and sets `aria-busy=\"true\"`. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-button label=\"Salvataggio in corso...\" await variant=\"primary\"></mds-button>\n```\n\n#### Form Participation\n\n`<mds-button>` is form-associated. Inside a `<form>` it natively triggers submit (`type=\"submit\"`, default) or reset (`type=\"reset\"`). Use `type=\"button\"` for any action that must not submit the form.\n\n```html\n<form action=\"/save\" method=\"post\">\n <mds-input-field label=\"Titolo\">\n <mds-input name=\"title\"></mds-input>\n </mds-input-field>\n\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Reimposta\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button type=\"button\" label=\"Anteprima\" variant=\"primary\" tone=\"text\"></mds-button>\n</form>\n```\n\n#### Several Actions That Submit One Form\n\nGive the buttons the same `name` and a different `value`, as with native submit buttons: the receiver reads which action was chosen from `name`.\n\n```html\n<form action=\"/mail\" method=\"post\">\n <mds-input-field label=\"Oggetto\">\n <mds-input name=\"subject\"></mds-input>\n </mds-input-field>\n\n <!-- the receiver gets action=send or action=draft -->\n <mds-button name=\"action\" value=\"send\" label=\"Invia\" variant=\"primary\"></mds-button>\n <mds-button name=\"action\" value=\"draft\" label=\"Salva come bozza\" tone=\"outline\"></mds-button>\n</form>\n```\n\nWhen your code handles the submit, build the form data with `event.submitter`, as for a native button: it carries the `name` / `value` of the button that was clicked.\n\n```js\nform.addEventListener('submit', (event) => {\n event.preventDefault();\n const data = new FormData(form, event.submitter);\n data.get('action'); // 'send' or 'draft'\n});\n```\n\nTo show one action and keep the others in a menu, use [`mds-button-dropdown`](../mds-button-dropdown/AGENTS.md) with `type=\"submit\"`: its primary action and its menu items send `name` / `value` the same way.\n\n#### Notification Badge via Named Slot\n\nThe `notification` slot accepts an `<mds-notification>`. This is the documented exception to the default-slot-is-text rule.\n\n```html\n<mds-button label=\"Notifiche\" icon=\"mi/baseline/notifications\" variant=\"primary\" tone=\"weak\">\n <mds-notification slot=\"notification\" value=\"12\"></mds-notification>\n</mds-button>\n```\n\n#### SSO Identity Variants\n\n`variant=\"google\"` and `variant=\"apple\"` apply the brand-correct chrome for SSO entry points. Do not reuse them for non-SSO buttons.\n\n```html\n<mds-button label=\"Accedi con Google\" variant=\"google\"></mds-button>\n<mds-button label=\"Accedi con Apple\" variant=\"apple\"></mds-button>\n```\n\n#### Styling Customization\n\nStyle the button only through its documented `--mds-button-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode, named themes and high contrast keep working.\n\n```css\n.featured-action mds-button {\n --mds-button-background: rgb(var(--magma-accent-emphasis));\n --mds-button-color: rgb(var(--magma-accent-on-emphasis));\n --mds-button-radius: var(--magma-radius-lg);\n --mds-button-gap: calc(var(--spacing) * 300);\n}\n```\n",
|
|
3588
|
+
"3. Antipattern": "Common incorrect uses of `<mds-button>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Put HTML in the Default Slot\n\nThe default slot accepts plain text only; nested elements are stripped or break layout. Use the `label` prop for text and the dedicated props/slots for everything else.\n\n```html\n<!-- INCORRECT -->\n<mds-button>\n <span class=\"bold\">Scarica</span>\n <small>(PDF)</small>\n</mds-button>\n\n<!-- CORRECT -->\n<mds-button label=\"Scarica (PDF)\" icon=\"mi/baseline/download\" variant=\"primary\"></mds-button>\n```\n\n#### Do Not Nest `<mds-button>` Inside an Anchor\n\nWrapping the button in `<a>` creates nested interactive controls, breaks keyboard semantics, and fails accessibility audits. Use the `href` prop on the component instead - it renders the link itself.\n\n```html\n<!-- INCORRECT -->\n<a href=\"/login\">\n <mds-button label=\"Accedi\"></mds-button>\n</a>\n\n<!-- CORRECT -->\n<mds-button label=\"Accedi\" href=\"/login\"></mds-button>\n```\n\n#### Do Not Follow the `href` Yourself in a Click Listener\n\nWith `href` set the component already renders a link the browser follows. Assigning `window.location` in a click listener loads the page a second time and takes a modifier click, which the browser would open in a new tab, into the current one. Either let the browser follow the link, or cancel the click and route on the client.\n\n```js\n// INCORRECT\nbutton.addEventListener('click', () => {\n window.location.href = button.href;\n});\n\n// CORRECT: a client-side router cancels the click and routes\nbutton.addEventListener('click', (event) => {\n if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;\n event.preventDefault();\n router.navigate(button.href);\n});\n```\n\n#### Icon-Only Buttons Without an Accessible Name\n\nWhen `label` is empty, the component derives a `title` from the last segment of the icon slug (\"delete\"), which names the icon, not the action. Always supply an explicit `aria-label` (or `title`) for icon-only buttons, or an `mds-tooltip` with `relation=\"label\"`.\n\n```html\n<!-- INCORRECT -->\n<mds-button icon=\"mi/baseline/delete\" variant=\"error\" tone=\"text\"></mds-button>\n\n<!-- CORRECT -->\n<mds-button\n icon=\"mi/baseline/delete\"\n aria-label=\"Elimina elemento\"\n variant=\"error\"\n tone=\"text\"\n></mds-button>\n```\n\n#### Do Not Build the Form Data Without the Submitter\n\n`new FormData(form)` leaves out the `name` / `value` of the button that submitted the form, as it does for a native submit button. Pass `event.submitter` to read which action was chosen; do not track the clicked button in a variable or a hidden input.\n\n```js\n// INCORRECT: action is missing\nform.addEventListener('submit', (event) => {\n event.preventDefault();\n const data = new FormData(form);\n});\n\n// CORRECT\nform.addEventListener('submit', (event) => {\n event.preventDefault();\n const data = new FormData(form, event.submitter);\n});\n```\n\n#### Do Not Slot `<mds-icon>` to Add an Icon\n\nThe component's `icon` prop renders the SVG through the shared icon-set service and positions it correctly via `icon-position`. Slotting `<mds-icon>` puts it in the text-only default slot, where it is stripped or misaligned.\n\n```html\n<!-- INCORRECT -->\n<mds-button>\n <mds-icon name=\"mi/baseline/add\"></mds-icon>\n Aggiungi\n</mds-button>\n\n<!-- CORRECT -->\n<mds-button label=\"Aggiungi\" icon=\"mi/baseline/add\" variant=\"primary\" tone=\"weak\"></mds-button>\n```\n\n#### Do Not Use Legacy `ghost` or `quiet` Tone Values\n\n`tone=\"ghost\"` and `tone=\"quiet\"` were renamed in Magma 2.0 to `outline` and `text`. The old values are no longer accepted by the typed `ToneBoxVariantType` and silently fall back to the default tone.\n\n```html\n<!-- INCORRECT (Magma 1.x naming) -->\n<mds-button label=\"Modifica\" tone=\"ghost\" variant=\"primary\"></mds-button>\n<mds-button label=\"Annulla\" tone=\"quiet\" variant=\"error\"></mds-button>\n\n<!-- CORRECT (Magma 2.x) -->\n<mds-button label=\"Modifica\" tone=\"outline\" variant=\"primary\"></mds-button>\n<mds-button label=\"Annulla\" tone=\"text\" variant=\"error\"></mds-button>\n```\n\n#### Customize via Documented Vars and Parts, Not Internal Selectors\n\nThe supported customization surface is `--mds-button-*` CSS custom properties plus the two documented shadow parts (`icon`, `label`). Targeting other internals via `::part()`, `>>>`, or undocumented class names couples your code to the Shadow DOM implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-button >>> .text {\n font-weight: bold;\n}\nmds-button::part(spinner) {\n color: red;\n}\n\n/* CORRECT */\nmds-button {\n --mds-button-color: rgb(var(--magma-accent-on-emphasis));\n --mds-button-radius: var(--magma-radius-lg);\n}\nmds-button::part(icon) {\n fill: rgb(var(--magma-warning-fg));\n}\n```\n"
|
|
3589
3589
|
},
|
|
3590
3590
|
"props": [
|
|
3591
3591
|
{
|
|
@@ -4488,7 +4488,7 @@
|
|
|
4488
4488
|
}
|
|
4489
4489
|
],
|
|
4490
4490
|
"usage": {
|
|
4491
|
-
"1. Description": "The `<mds-button-dropdown>` web component is a split-button control of the Magma Design System: it pairs a primary `<mds-button>` action with a secondary chevron button that opens an attached `<mds-dropdown>`, giving users a default action plus a menu of related choices in a single, visually unified control.\n\n#### Semantic Behavior\n\n- **Default slot is the menu**: Whatever you place in the default slot becomes the dropdown panel content; it is not treated as the button label (the visible label comes from the `label` prop).\n- **Chevron trigger**: The second button is icon-only (chevron) and toggles the dropdown.\n- **Shared configuration**: `active`, `autoFocus`, `await`, `disabled`, `href`, `target`, `size`, `tone` and `variant` are forwarded identically to both internal buttons, so the two halves always stay visually and behaviorally in sync.\n- **Form association**: The host is form-associated. With `type=\"submit\"` the primary action submits the enclosing `<form>` (or the one its `form` attribute names) and sends `name=value`, like a native submit button; with `type=\"reset\"` it resets it. The chevron never submits. Unlike `<mds-button>`, `type` defaults to `'button'`: a dropdown in a form submits it only when asked. The menu items are slotted `<mds-button>`, so they follow their own `type` (default `'submit'`), `name` and `value`, and the receiver tells all the actions apart by `name`.\n- **Disabled / await states**: Because these flags pass through to both buttons, disabling or putting the control in an awaiting state affects the action and the trigger together. A disabled `<fieldset>` around the component disables both halves the same way, without setting `disabled`.\n- **Primary action event**: `mdsButtonDropdownClick` fires when the primary action is clicked or activated from the keyboard, and not while the component is `disabled` or awaiting. The chevron and the menu items do not fire it. A native `click` listener on the component also runs for the menu items, whose clicks bubble to it, so listen for `mdsButtonDropdownClick` to run the primary action in JavaScript.\n- **Dropdown part**: The internal dropdown is exposed as the `dropdown` shadow part for external styling of the menu surface.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` / `tone` / `size` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md); they apply here as in `<mds-button>`, narrowed to `tone` `strong` / `weak` and without the `google` / `apple` variants, and are forwarded to both internal buttons. `variant` defaults to `'primary'`, `tone` defaults to `'strong'`, and `size` defaults to `'md'`.\n\n- **`label`** sets the text of the primary action button only; the chevron trigger is icon-only.\n- **`type`** (default `'button'`), **`name`** and **`value`** apply to the primary action only, as described under Form association. The menu items follow their own `type`: inside a `<form>`, give `type=\"button\"` to the ones that must not submit it.\n- **`href`** makes a click navigate instead of submitting, with `target` choosing `'self'` vs `'blank'`; it is forwarded to the chevron too, which then navigates as well as opening the menu.\n\n#### Other behavioral props\n\n- **`icon`** is an SVG filename slug from the Magma icon library, applied to the primary action button (the chevron icon on the trigger is fixed and not configurable).\n- **`truncate`** is declared (default `'word'`) but not forwarded to the internal buttons: the primary label always truncates as `'word'`.\n",
|
|
4491
|
+
"1. Description": "The `<mds-button-dropdown>` web component is a split-button control of the Magma Design System: it pairs a primary `<mds-button>` action with a secondary chevron button that opens an attached `<mds-dropdown>`, giving users a default action plus a menu of related choices in a single, visually unified control.\n\n#### Semantic Behavior\n\n- **Default slot is the menu**: Whatever you place in the default slot becomes the dropdown panel content; it is not treated as the button label (the visible label comes from the `label` prop).\n- **Chevron trigger**: The second button is icon-only (chevron), named in the page language (the `lang` of `<html>`) (\"More actions\"), and toggles the dropdown; it carries `aria-haspopup` and `aria-expanded` for the menu it opens.\n- **Shared configuration**: `active`, `autoFocus`, `await`, `disabled`, `href`, `target`, `size`, `tone` and `variant` are forwarded identically to both internal buttons, so the two halves always stay visually and behaviorally in sync.\n- **Form association**: The host is form-associated. With `type=\"submit\"` the primary action submits the enclosing `<form>` (or the one its `form` attribute names) and sends `name=value`, like a native submit button; with `type=\"reset\"` it resets it. The chevron never submits. Unlike `<mds-button>`, `type` defaults to `'button'`: a dropdown in a form submits it only when asked. The menu items are slotted `<mds-button>`, so they follow their own `type` (default `'submit'`), `name` and `value`, and the receiver tells all the actions apart by `name`.\n- **Disabled / await states**: Because these flags pass through to both buttons, disabling or putting the control in an awaiting state affects the action and the trigger together. A disabled `<fieldset>` around the component disables both halves the same way, without setting `disabled`.\n- **Primary action event**: `mdsButtonDropdownClick` fires when the primary action is clicked or activated from the keyboard, and not while the component is `disabled` or awaiting. The chevron and the menu items do not fire it. A native `click` listener on the component also runs for the menu items, whose clicks bubble to it, so listen for `mdsButtonDropdownClick` to run the primary action in JavaScript.\n- **Dropdown part**: The internal dropdown is exposed as the `dropdown` shadow part for external styling of the menu surface.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` / `tone` / `size` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md); they apply here as in `<mds-button>`, narrowed to `tone` `strong` / `weak` and without the `google` / `apple` variants, and are forwarded to both internal buttons. `variant` defaults to `'primary'`, `tone` defaults to `'strong'`, and `size` defaults to `'md'`.\n\n- **`label`** sets the text of the primary action button only; the chevron trigger is icon-only.\n- **`type`** (default `'button'`), **`name`** and **`value`** apply to the primary action only, as described under Form association. The menu items follow their own `type`: inside a `<form>`, give `type=\"button\"` to the ones that must not submit it.\n- **`href`** makes a click navigate instead of submitting, with `target` choosing `'self'` vs `'blank'`; it is forwarded to the chevron too, which then navigates as well as opening the menu.\n\n#### Other behavioral props\n\n- **`icon`** is an SVG filename slug from the Magma icon library, applied to the primary action button (the chevron icon on the trigger is fixed and not configurable).\n- **`truncate`** is declared (default `'word'`) but not forwarded to the internal buttons: the primary label always truncates as `'word'`.\n",
|
|
4492
4492
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-button-dropdown>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Split Button with Menu Items\n\nThe canonical form: a `label` prop for the primary action and one or more [`mds-button`](../mds-button/AGENTS.md) elements in the default slot as menu choices. Give the slot items `variant=\"dark\" tone=\"text\"` to keep them visually neutral inside the dropdown panel.\n\n```html\n<mds-button-dropdown label=\"Salva come bozza\" variant=\"success\" tone=\"weak\">\n <mds-button icon=\"mi/baseline/send\" variant=\"dark\" tone=\"text\" label=\"Invia subito\"></mds-button>\n <mds-button icon=\"mi/baseline/delete\" variant=\"dark\" tone=\"text\" label=\"Elimina\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Variant and Tone for Emphasis\n\nUse `variant` to express meaning and `tone` to express weight - the same pair applies to both internal buttons automatically.\n\n```html\n<!-- High emphasis: primary action -->\n<mds-button-dropdown label=\"Pubblica\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Pubblica come bozza\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Pianifica pubblicazione\"></mds-button>\n</mds-button-dropdown>\n\n<!-- Status emphasis: destructive action group -->\n<mds-button-dropdown label=\"Elimina voce\" variant=\"error\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Elimina e archivia\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Annulla eliminazione\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Sizing\n\nUse the `size` prop. Both internal buttons track it automatically.\n\n```html\n<mds-button-dropdown label=\"Azione\" size=\"sm\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"md\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"lg\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"xl\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Primary Action with an Icon\n\nSupply the `icon` prop to add an icon to the primary action button. The chevron trigger icon is fixed and not configurable.\n\n```html\n<mds-button-dropdown\n label=\"Carica documento\"\n icon=\"mi/baseline/upload\"\n variant=\"primary\"\n tone=\"weak\"\n>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Carica da URL\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Carica da Drive\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while a request is in flight. Both the action button and the chevron trigger become unavailable simultaneously. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-button-dropdown label=\"Salvataggio in corso...\" await variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Salva e chiudi\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Salva come copia\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Disabled State\n\nThe `disabled` attribute blocks both halves of the control together.\n\n```html\n<mds-button-dropdown label=\"Invia richiesta\" disabled variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Invia in bozza\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Primary Action Handled in JavaScript\n\nListen for `mdsButtonDropdownClick` to run the primary action: it comes from the primary action only, from a click or the keyboard, and not while the component is `disabled` or awaiting. Handle each menu item with its own `click`.\n\n```html\n<mds-button-dropdown id=\"save\" label=\"Salva\" variant=\"primary\">\n <mds-button id=\"save-copy\" variant=\"dark\" tone=\"text\" label=\"Salva come copia\"></mds-button>\n</mds-button-dropdown>\n\n<script>\n document.getElementById('save').addEventListener('mdsButtonDropdownClick', () => save());\n document.getElementById('save-copy').addEventListener('click', () => saveCopy());\n</script>\n```\n\n#### Several Actions That Submit One Form\n\nSet `type=\"submit\"` on the component and give the primary action and the menu items the same `name` with a different `value`: each action submits the form, and the receiver reads which one was chosen from `name`, as with native submit buttons. Give `type=\"button\"` to the menu items that must not submit.\n\n```html\n<form action=\"/mail\" method=\"post\">\n <mds-input-field label=\"Oggetto\">\n <mds-input name=\"subject\"></mds-input>\n </mds-input-field>\n\n <!-- the receiver gets action=send, action=draft or action=schedule -->\n <mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\" variant=\"primary\">\n <mds-button name=\"action\" value=\"draft\" variant=\"dark\" tone=\"text\" label=\"Salva come bozza\"></mds-button>\n <mds-button name=\"action\" value=\"schedule\" variant=\"dark\" tone=\"text\" label=\"Invio programmato\"></mds-button>\n <mds-button type=\"button\" variant=\"dark\" tone=\"text\" label=\"Anteprima\"></mds-button>\n </mds-button-dropdown>\n</form>\n```\n\nWhen your code handles the submit, build the form data with `event.submitter`, as for [`mds-button`](../mds-button/AGENTS.md): `new FormData(form, event.submitter)`.\n\n#### Hyperlink Split Button via `href`\n\n`href` and `target` on the component are forwarded to both internal buttons, the chevron included: a click on the chevron navigates as well as opening the menu. Keep `href` off the component, handle the primary action with `mdsButtonDropdownClick`, and put the links on the menu items (`target=\"blank\"` opens them in a new tab).\n\n```html\n<mds-button-dropdown\n label=\"Apri documento\"\n variant=\"primary\"\n tone=\"weak\"\n>\n <mds-button href=\"https://example.com/doc/edit\" target=\"blank\" variant=\"dark\" tone=\"text\" label=\"Modifica\"></mds-button>\n <mds-button href=\"https://example.com/doc/history\" target=\"blank\" variant=\"dark\" tone=\"text\" label=\"Cronologia\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Styling Customization\n\nStyle the component through its documented `--mds-button-dropdown-*` CSS custom properties or the `dropdown` shadow part. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and named themes keep working.\n\n```css\n.custom-toolbar mds-button-dropdown {\n --mds-button-dropdown-radius: var(--magma-radius-md);\n}\n\n/* Style the dropdown panel surface through the documented shadow part */\n.custom-toolbar mds-button-dropdown::part(dropdown) {\n box-shadow: var(--shadow-lg);\n}\n```\n",
|
|
4493
4493
|
"3. Antipattern": "Common incorrect uses of `<mds-button-dropdown>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Put the Label in the Default Slot\n\nThe default slot feeds the `<mds-dropdown>` panel, not the button label. Text placed in the slot ends up as menu content, not as the button's visible text. Use the `label` prop.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown variant=\"primary\" tone=\"strong\">\n Salva\n</mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown label=\"Salva\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Salva come bozza\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Slot Non-Button Content as Menu Items\n\nThe dropdown panel is designed for [`mds-button`](../mds-button/AGENTS.md) elements. Slotting raw `<button>`, `<a>`, or arbitrary HTML bypasses the Magma theming, focus styles and button API (`icon`, `await`, `disabled`) of the menu entries.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown label=\"Esporta\" variant=\"primary\" tone=\"weak\">\n <button onclick=\"exportPDF()\">PDF</button>\n <a href=\"/export/csv\">CSV</a>\n</mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown label=\"Esporta\" variant=\"primary\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Esporta PDF\" icon=\"mi/baseline/picture-as-pdf\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Esporta CSV\" icon=\"mi/baseline/table-chart\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Count on the Default `type` to Submit a Form\n\nUnlike `<mds-button>`, the component defaults to `type=\"button\"`: inside a form, the primary action submits nothing until you set `type=\"submit\"`.\n\n```html\n<!-- INCORRECT: the primary action does not submit -->\n<form action=\"/mail\" method=\"post\">\n <mds-button-dropdown name=\"action\" value=\"send\" label=\"Invia\">\n <mds-button name=\"action\" value=\"draft\" variant=\"dark\" tone=\"text\" label=\"Salva come bozza\"></mds-button>\n </mds-button-dropdown>\n</form>\n\n<!-- CORRECT -->\n<form action=\"/mail\" method=\"post\">\n <mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\">\n <mds-button name=\"action\" value=\"draft\" variant=\"dark\" tone=\"text\" label=\"Salva come bozza\"></mds-button>\n </mds-button-dropdown>\n</form>\n```\n\n#### Do Not Submit the Form from a `click` Listener\n\nA `click` listener on the component also runs for the menu items, whose clicks bubble to it: picking a menu item that submits (\"Salva come bozza\") submits the form twice, once with its `name` / `value` and once without, and the receiver cannot tell which action was chosen. Use `type=\"submit\"` with `name` / `value`.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown id=\"send\" label=\"Invia\"></mds-button-dropdown>\n<script>\n document.getElementById('send').addEventListener('click', () => form.requestSubmit());\n</script>\n\n<!-- CORRECT -->\n<mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\"></mds-button-dropdown>\n```\n\n#### Do Not Listen to `click` for the Primary Action\n\nA `click` on the component also comes from the menu items, whose clicks bubble to it: the primary action would run whenever the user picks an entry of the menu. Listen for `mdsButtonDropdownClick`, which only the primary action emits.\n\n```js\n// INCORRECT: also runs for \"Salva come copia\"\ndropdown.addEventListener('click', () => save());\n\n// CORRECT\ndropdown.addEventListener('mdsButtonDropdownClick', () => save());\n```\n\n#### Do Not Leave a Menu Item That Must Not Submit on the Default `type`\n\nThe menu items are slotted `<mds-button>`, whose `type` defaults to `'submit'`: inside a form, an item that runs your own code (a preview, a copy) submits the form too. Give it `type=\"button\"`.\n\n```html\n<!-- INCORRECT: \"Anteprima\" submits the form -->\n<mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Anteprima\"></mds-button>\n</mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\">\n <mds-button type=\"button\" variant=\"dark\" tone=\"text\" label=\"Anteprima\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Use Unsupported `tone` Values\n\n`<mds-button-dropdown>` accepts `ToneMinimalVariantType`, which is `strong` and `weak` only. Passing `outline`, `text`, or `box` is not valid for this component: the value reaches the internal buttons unchecked, without the split-button styling that only `strong` and `weak` have.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown label=\"Azione\" variant=\"primary\" tone=\"outline\"></mds-button-dropdown>\n<mds-button-dropdown label=\"Azione\" variant=\"primary\" tone=\"text\"></mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown label=\"Azione\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione\"></mds-button>\n</mds-button-dropdown>\n<mds-button-dropdown label=\"Azione\" variant=\"primary\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Try to Customize the Chevron Icon\n\nThe chevron trigger icon is internal and fixed. There is no prop to change it. Do not attempt to override it with CSS property hacks or shadow-DOM selectors.\n\n```css\n/* INCORRECT */\nmds-button-dropdown .dropdown-action mds-icon {\n content: url('custom-arrow.svg');\n}\n\n/* CORRECT - style only through documented custom properties and the dropdown part */\nmds-button-dropdown {\n --mds-button-dropdown-radius: var(--magma-radius-md);\n}\nmds-button-dropdown::part(dropdown) {\n box-shadow: var(--shadow-lg);\n}\n```\n\n#### Do Not Set Boolean Attributes to `\"false\"`\n\n`await`, `disabled`, and `active` are boolean attributes. The component reads the string `\"false\"` as `false` and drops the attribute when it renders, but until then the attribute is in the DOM and attribute selectors (`mds-button-dropdown[disabled]`) match it. Remove the attribute to turn it off.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown label=\"Invia\" await=\"false\" disabled=\"false\" variant=\"primary\"></mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown label=\"Invia\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Invia come bozza\"></mds-button>\n</mds-button-dropdown>\n```\n"
|
|
4494
4494
|
},
|
|
@@ -5127,7 +5127,7 @@
|
|
|
5127
5127
|
}
|
|
5128
5128
|
],
|
|
5129
5129
|
"usage": {
|
|
5130
|
-
"1. Description": "The `<mds-calendar>` web component is the date-selection surface of the Magma Design System: a localized month grid that lets users pick either a single day or a date range. It is the visual engine behind `mds-input-date` and `mds-input-date-range`.\n\n#### Semantic Behavior\n\n- **Range vs. single mode**: range selection is the default; set `singlePicker` to pick one day. In range mode the first click sets the start, the second sets the end, and a third click starts a new range from the clicked day; in single mode each click replaces the prior choice.\n- **Range auto-ordering**: If the second click lands before the current start, the two endpoints are swapped so `startDate` always precedes `endDate`; an `endDate` set earlier than `startDate` is not reordered: changed after load, it only logs 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 in the page language (the `lang` attribute of `<html>`, `en` when absent).\n- **Emitted events**: `mdsCalendarChange` fires on every pick with `{ startDate, endDate? }`: in range mode the first click emits `{ startDate }` alone, the second the full range; `mdsCalendarPreselect` fires only with a completed range, to let preselection shortcuts re-evaluate their state.\n- **Preselection slot**: A `preselection` named slot hosts quick-pick shortcuts. The area appears only if, when the calendar loads, the host contains an element with the class `date-preselection--has-preselection`; `hidePreselection` collapses it.\n\n#### Properties & Visual Configurations\n\nDates are exchanged as ISO 8601 strings (`YYYY-MM-DD`). `startDate` and `endDate` seed the selection (a click updates the internal selection and emits `mdsCalendarChange`, it does not rewrite the attributes); on load, a valid `startDate` also determines which month is shown first.\n\n- **`singlePicker`** is the mode switch: omit it for two-ended range selection, set it for single-day pickers. When set, any `endDate` is ignored and cleared with a warning.\n- **`hidePreviousButton`** / **`hideNextButton`** remove one of the header navigation buttons, typically on calendars paired side by side; **`disableMonthYearSelection`** keeps the header on the day grid; **`hideToday`** removes the highlight on today's date.\n- Every boolean prop defaults to `false`: the feature is on until the bare attribute turns it off.\n- **`min`** / **`max`** define the selectable window; days outside it render disabled rather than being hidden.\n\nThis component does not use the shared `variant` / `tone` ladders on its host - those are defined in [`agents/variants.md`](../../../../agents/variants.md) and are applied internally to the navigation buttons it renders.\n",
|
|
5130
|
+
"1. Description": "The `<mds-calendar>` web component is the date-selection surface of the Magma Design System: a localized month grid that lets users pick either a single day or a date range. It is the visual engine behind `mds-input-date` and `mds-input-date-range`.\n\n#### Semantic Behavior\n\n- **Range vs. single mode**: range selection is the default; set `singlePicker` to pick one day. In range mode the first click sets the start, the second sets the end, and a third click starts a new range from the clicked day; in single mode each click replaces the prior choice.\n- **Range auto-ordering**: If the second click lands before the current start, the two endpoints are swapped so `startDate` always precedes `endDate`; an `endDate` set earlier than `startDate` is not reordered: changed after load, it only logs a console warning.\n- **Hover preview**: While a range start is set, hovering over cells previews the candidate range live (range mode only).\n- **Min/max bounds**: `min` and `max` mark out-of-range day cells as disabled, blocking their selection.\n- **Multi-view navigation**: The header toggles between the day grid, a month picker, and a year picker; the year view pages in decades while the calendar view pages month by month. The two arrows are icon-only buttons named in the page language (the `lang` of `<html>`): previous / next month on the day grid, previous / next years in the year view; the month picker has nothing to page through, so there they are disabled.\n- **Localization**: Weekday names, month names, and cell titles are formatted in the page language (the `lang` attribute of `<html>`, `en` when absent).\n- **Emitted events**: `mdsCalendarChange` fires on every pick with `{ startDate, endDate? }`: in range mode the first click emits `{ startDate }` alone, the second the full range; `mdsCalendarPreselect` fires only with a completed range, to let preselection shortcuts re-evaluate their state.\n- **Preselection slot**: A `preselection` named slot hosts quick-pick shortcuts. The area appears only if, when the calendar loads, the host contains an element with the class `date-preselection--has-preselection`; `hidePreselection` collapses it.\n\n#### Properties & Visual Configurations\n\nDates are exchanged as ISO 8601 strings (`YYYY-MM-DD`). `startDate` and `endDate` seed the selection (a click updates the internal selection and emits `mdsCalendarChange`, it does not rewrite the attributes); on load, a valid `startDate` also determines which month is shown first.\n\n- **`singlePicker`** is the mode switch: omit it for two-ended range selection, set it for single-day pickers. When set, any `endDate` is ignored and cleared with a warning.\n- **`hidePreviousButton`** / **`hideNextButton`** remove one of the header navigation buttons, typically on calendars paired side by side; **`disableMonthYearSelection`** keeps the header on the day grid; **`hideToday`** removes the highlight on today's date.\n- Every boolean prop defaults to `false`: the feature is on until the bare attribute turns it off.\n- **`min`** / **`max`** define the selectable window; days outside it render disabled rather than being hidden.\n\nThis component does not use the shared `variant` / `tone` ladders on its host - those are defined in [`agents/variants.md`](../../../../agents/variants.md) and are applied internally to the navigation buttons it renders.\n",
|
|
5131
5131
|
"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 shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Single-Day Picker\n\nSet the bare `single-picker` attribute for a plain single-date selector. `mdsCalendarChange` fires once with `{ startDate }` and no `endDate`. Seed an initial date via `start-date`.\n\n```html\n<mds-calendar single-picker start-date=\"2025-06-10\"></mds-calendar>\n\n<script>\n document.querySelector('mds-calendar').addEventListener('mdsCalendarChange', (e) => {\n console.log('Data selezionata:', e.detail.startDate);\n });\n</script>\n```\n\n#### Range Picker (default mode)\n\nRange selection is the default: omit `single-picker`. The first click sets the start date, the second sets the end date. A third click starts a new range from the clicked day. `mdsCalendarChange` fires on both clicks: after the first one `endDate` is absent. Preload a range by supplying both `start-date` and `end-date`.\n\n```html\n<mds-calendar start-date=\"2025-09-01\" end-date=\"2025-09-15\"></mds-calendar>\n\n<script>\n document.querySelector('mds-calendar').addEventListener('mdsCalendarChange', (e) => {\n const { startDate, endDate } = e.detail;\n console.log('Intervallo selezionato:', startDate, '-', endDate);\n });\n</script>\n```\n\n#### Restricting the Selectable Window with `min` / `max`\n\nPass ISO 8601 strings to `min` and `max` to mark out-of-range days as disabled. Days outside the window are not hidden - they remain visible but cannot be clicked.\n\n```html\n<mds-calendar\n single-picker\n min=\"2025-01-01\"\n max=\"2025-12-31\"\n></mds-calendar>\n```\n\n#### Navigating to a Specific Month Programmatically\n\nUse the `updateCurrentDate` method to jump the visible month without changing the current selection. Pass any ISO date string that falls within the target month.\n\n```html\n<mds-calendar id=\"cal\" single-picker></mds-calendar>\n\n<script>\n document.querySelector('#cal').updateCurrentDate('2026-03-01');\n</script>\n```\n\n#### Quick-Pick Preselection Shortcuts\n\nThe `preselection` named slot hosts your own shortcuts, for example `mds-button` elements whose `click` sets `start-date` / `end-date` ([`mds-input-date-range-preselection`](../mds-input-date-range-preselection/AGENTS.md) works only inside `mds-input-date-range`). The slot panel becomes visible only if, when the calendar loads, the host contains an element with the class `date-preselection--has-preselection`; set `hide-preselection` to keep it collapsed. `mdsCalendarPreselect` fires after each completed range selection so the shortcuts can re-evaluate their active state.\n\n```html\n<mds-calendar start-date=\"2025-09-01\" end-date=\"2025-09-07\">\n <div slot=\"preselection\" class=\"date-preselection--has-preselection\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Ultimi 7 giorni\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Ultimi 30 giorni\"></mds-button>\n </div>\n</mds-calendar>\n```\n\n#### Paired Calendars Without Duplicate Navigation\n\nTwo calendars shown side by side (the pattern used by `mds-input-date-range` on wide viewports) should expose one previous and one next button in total: hide the inner buttons with `hide-previous-button` / `hide-next-button` and lock the header on the day grid with `disable-month-year-selection`, then keep the two `view-date` values one month apart from the `mdsCalendarNavigate` event.\n\n```html\n<mds-calendar id=\"start\" view-date=\"2025-09-01\" hide-next-button disable-month-year-selection></mds-calendar>\n<mds-calendar id=\"end\" view-date=\"2025-10-01\" hide-previous-button disable-month-year-selection></mds-calendar>\n```\n\n#### Listening for Selection Changes\n\nListen on the documented `mdsCalendarChange` event - not the native `change` event - so the handler receives the structured `{ startDate, endDate? }` detail object directly from the Shadow DOM.\n\n```html\n<mds-calendar id=\"picker\" single-picker></mds-calendar>\n\n<script>\n document.querySelector('#picker').addEventListener('mdsCalendarChange', (e) => {\n const { startDate } = e.detail;\n document.querySelector('#output').textContent = 'Scadenza: ' + startDate;\n });\n</script>\n```\n\n#### Embedded inside `mds-input-date` or `mds-input-date-range`\n\n`<mds-calendar>` is the visual engine used internally by [`mds-input-date`](../mds-input-date/AGENTS.md) and [`mds-input-date-range`](../mds-input-date-range/AGENTS.md). In most product surfaces, reach for those higher-level components. Use `<mds-calendar>` directly only when you need a standalone always-visible date grid without an associated text input.\n\n```html\n<!-- Higher-level: input with calendar overlay -->\n<mds-input-field label=\"Scadenza\">\n <mds-input-date name=\"scadenza\"></mds-input-date>\n</mds-input-field>\n\n<!-- Lower-level: always-visible standalone grid -->\n<mds-calendar single-picker></mds-calendar>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nAdjust the calendar appearance only through the documented `--mds-calendar-*` CSS custom properties. Set them on the host element or a parent selector; use the semantic color roles so dark mode, named themes and high contrast keep working.\n\n```css\n.booking-widget mds-calendar {\n --mds-calendar-background: rgb(var(--magma-surface-muted));\n --mds-calendar-border-radius: var(--magma-radius-xl);\n --mds-calendar-padding: calc(var(--spacing) * 500);\n --mds-calendar-cell-gap: calc(var(--spacing) * 100);\n --mds-calendar-cell-other-month-visibility: hidden;\n}\n```\n",
|
|
5132
5132
|
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Toggle Single Mode with a Quoted Boolean String\n\n`singlePicker` is a boolean prop that defaults to `false`. The component reads the string `\"false\"` as `false`, but the prop is not reflected, so `single-picker=\"false\"` stays in the DOM and attribute selectors (`mds-calendar[single-picker]`) and any code reading the attribute still see it set. Use the bare attribute for single mode and omit it for the default range mode; toggle it at runtime by adding/removing the attribute or setting the property in JavaScript.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar single-picker=\"false\"></mds-calendar>\n\n<!-- CORRECT -->\n<mds-calendar></mds-calendar>\n<mds-calendar id=\"cal\" single-picker></mds-calendar>\n<script>\n document.querySelector('#cal').singlePicker = false; // back to range mode\n</script>\n```\n\n#### Do Not Set `end-date` When `single-picker` Is Set\n\nWhen `singlePicker` is set, the component rejects `endDate` with a console warning and clears it internally. Setting both `single-picker` and `end-date` is contradictory and produces no visible selection for the end date.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar single-picker start-date=\"2025-06-01\" end-date=\"2025-06-15\"></mds-calendar>\n\n<!-- CORRECT -->\n<mds-calendar single-picker start-date=\"2025-06-01\"></mds-calendar>\n```\n\n#### Do Not Provide `startDate` After `endDate`\n\nDates must be chronologically ordered: `startDate` must precede `endDate`. The component does not reorder them: set at load, the two ends are marked with no range between them; changed later, it only logs a console warning. Always ensure `start-date <= end-date`.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar start-date=\"2025-12-31\" end-date=\"2025-12-01\"></mds-calendar>\n\n<!-- CORRECT -->\n<mds-calendar start-date=\"2025-12-01\" end-date=\"2025-12-31\"></mds-calendar>\n```\n\n#### Do Not Listen for the Native `change` Event\n\n`<mds-calendar>` does not bubble a native `change` event from inside its Shadow DOM. Use the documented `mdsCalendarChange` custom event so the handler reliably receives the structured `{ startDate, endDate? }` payload.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar id=\"cal\"></mds-calendar>\n<script>\n document.querySelector('#cal').addEventListener('change', (e) => {\n console.log(e.target.value); // undefined - wrong event\n });\n</script>\n\n<!-- CORRECT -->\n<mds-calendar id=\"cal\"></mds-calendar>\n<script>\n document.querySelector('#cal').addEventListener('mdsCalendarChange', (e) => {\n console.log(e.detail.startDate, e.detail.endDate);\n });\n</script>\n```\n\n#### Do Not Use `<mds-calendar>` as a Drop-In Replacement for `mds-input-date`\n\n`<mds-calendar>` is not form-associated and emits no `name`/`value` pair for form submission. When you need a date picker tied to a form field, use [`mds-input-date`](../mds-input-date/AGENTS.md) (single date) or [`mds-input-date-range`](../mds-input-date-range/AGENTS.md) (range) instead.\n\n```html\n<!-- INCORRECT -->\n<form action=\"/prenota\" method=\"post\">\n <mds-calendar name=\"check-in\" single-picker></mds-calendar>\n <mds-button type=\"submit\" label=\"Prenota\"></mds-button>\n</form>\n\n<!-- CORRECT -->\n<form action=\"/prenota\" method=\"post\">\n <mds-input-field label=\"Data di arrivo\">\n <mds-input-date name=\"check-in\"></mds-input-date>\n </mds-input-field>\n <mds-button type=\"submit\" label=\"Prenota\"></mds-button>\n</form>\n```\n\n#### Do Not Style Internals via Undocumented `::part()` Selectors\n\nThe only supported customization surface is the set of `--mds-calendar-*` CSS custom properties. Targeting shadow-DOM internals with `::part()` selectors that are not in the documentation couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-calendar::part(nav) {\n background: red;\n}\nmds-calendar::part(cell) {\n border: 1px solid blue;\n}\n\n/* CORRECT */\nmds-calendar {\n --mds-calendar-background: rgb(var(--magma-surface-muted));\n --mds-calendar-border-radius: var(--magma-radius-xl);\n --mds-calendar-cell-other-month-visibility: hidden;\n}\n```\n"
|
|
5133
5133
|
},
|
|
@@ -7200,8 +7200,8 @@
|
|
|
7200
7200
|
"filePath": "src/components/mds-dropdown/mds-dropdown.tsx",
|
|
7201
7201
|
"encapsulation": "shadow",
|
|
7202
7202
|
"tag": "mds-dropdown",
|
|
7203
|
-
"readme": "# mds-dropdown\n\n
|
|
7204
|
-
"docs": "",
|
|
7203
|
+
"readme": "# mds-dropdown\n\n\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
|
|
7204
|
+
"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.",
|
|
7205
7205
|
"docsTags": [
|
|
7206
7206
|
{
|
|
7207
7207
|
"name": "slot",
|
|
@@ -7892,11 +7892,11 @@
|
|
|
7892
7892
|
"filePath": "src/components/mds-emoji/mds-emoji.tsx",
|
|
7893
7893
|
"encapsulation": "shadow",
|
|
7894
7894
|
"tag": "mds-emoji",
|
|
7895
|
-
"readme": "# mds-emoji\n\
|
|
7896
|
-
"docs": "
|
|
7895
|
+
"readme": "# mds-emoji\n\n\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
|
|
7896
|
+
"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.",
|
|
7897
7897
|
"docsTags": [],
|
|
7898
7898
|
"usage": {
|
|
7899
|
-
"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. When the user prefers reduced motion, neither the pointer tracking nor the blinking moves the face.\n- **Single-animation lock**: Only one expression plays at a time - `agree`, `smile`, `disagree`, and `startThinking` take the face over: each stops whatever is playing (a thinking pose included) and starts from the neutral face, so a later call cuts an earlier one short. `startThinking` is a no-op only while the emoji is already thinking.\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, mouse-following is restarted if `startFollowMouse()` was ever called, even after a later `stopFollowMouse()`.\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",
|
|
7899
|
+
"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. The illustrations are drawn in the [Magma Emoji](https://www.figma.com/design/09SuDQMZYyOKGyomr87G9c/Emoji?node-id=0-1&t=U3txjHfdwaMIRRAC-1) Figma file.\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. When the user prefers reduced motion, neither the pointer tracking nor the blinking moves the face.\n- **Single-animation lock**: Only one expression plays at a time - `agree`, `smile`, `disagree`, and `startThinking` take the face over: each stops whatever is playing (a thinking pose included) and starts from the neutral face, so a later call cuts an earlier one short. `startThinking` is a no-op only while the emoji is already thinking.\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, mouse-following is restarted if `startFollowMouse()` was ever called, even after a later `stopFollowMouse()`.\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",
|
|
7900
7900
|
"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 shared component rules in [`agents/conventions.md`](../../../../agents/conventions.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. Without awaiting they still never overlap, but each call takes the face over and cuts the previous expression short.\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 the semantic color roles (`rgb(var(--magma-<role>))`) so dark mode and named themes keep working; Simi's skin tones are data, so hex values are fine there.\n\n```css\n/* Theming Mia for a custom brand */\nmds-emoji[name='mia'] {\n --mds-emoji-mia-head-color: rgb(var(--magma-accent-surface-hover));\n --mds-emoji-mia-eyes-color: rgb(var(--magma-accent-emphasis-hover));\n --mds-emoji-mia-mouth-color: rgb(var(--magma-accent-emphasis));\n --mds-emoji-mia-hands-color: rgb(var(--magma-accent-emphasis));\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",
|
|
7901
7901
|
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - 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: no mascot is rendered and the component throws a `TypeError` in the console.\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\n`agree()`, `smile()`, `disagree()`, and `startThinking()` each take the face over: they stop whatever is playing (a thinking pose included) and start from the neutral face. Firing them without awaiting the previous call cuts the earlier expression short.\n\n```html\n<!-- INCORRECT - the second call cuts the first one short -->\n<script>\n emoji.startThinking(); // starts thinking\n emoji.agree(); // takes over: the thinking pose is dropped at once\n</script>\n\n<!-- CORRECT - await each expression before chaining the next -->\n<script type=\"module\">\n const emoji = document.querySelector('mds-emoji');\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: `stopThinking()` returns at once unless the emoji is thinking. An expression runs to completion unless another expression takes the face over.\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 type=\"module\">\n const emoji = document.querySelector('mds-emoji');\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 const emoji = document.querySelector('mds-emoji');\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"
|
|
7902
7902
|
},
|
|
@@ -8749,8 +8749,8 @@
|
|
|
8749
8749
|
"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.",
|
|
8750
8750
|
"docsTags": [],
|
|
8751
8751
|
"usage": {
|
|
8752
|
-
"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 `description` (the `description` prop, or else the untranslated key of the detected type, such as `documentAdobe`), `extension`, `filename`, the host element as `target`, and the detected `type`/format.\n- **Downloaded persistence**: On click the component records the file as downloaded in `localStorage
|
|
8753
|
-
"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 shared component rules in [`agents/conventions.md`](../../../../agents/conventions.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 Adobe\" for a 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\nThe component
|
|
8752
|
+
"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 `description` (the `description` prop, or else the untranslated key of the detected type, such as `documentAdobe`), `extension`, `filename`, the host element as `target`, and the detected `type`/format.\n- **Downloaded persistence**: On click the component records the file as downloaded in `localStorage`, under a key derived from the filename with a small non-cryptographic hash. Every later render of the same filename on the same origin shows the \"done\" indicator.\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, split at the last dot so the dots inside the name are kept (`report.v2.final.docx` shows `report.v2.final` and `.docx`; a leading dot belongs to the name, as in `.env`); the extension is 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",
|
|
8753
|
+
"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 shared component rules in [`agents/conventions.md`](../../../../agents/conventions.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 Adobe\" for a 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\nThe component shows a \"done\" indicator once the file has been downloaded, on every later render of the same filename. 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. Magma 1 used `show-downloaded-icon=\"false\"`; that prop no longer exists (the codemod turns it into `hide-downloaded-icon`).\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 the semantic color roles via `rgb(var(--magma-<role>))` 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(--magma-accent-fg));\n --mds-file-preview-icon-background: rgb(var(--magma-accent-surface-subtle));\n --mds-file-preview-color: rgb(var(--magma-accent-fg));\n}\n```\n",
|
|
8754
8754
|
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - 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 has no `href`. 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(--magma-accent-surface-subtle));\n --mds-file-preview-icon-color: rgb(var(--magma-accent-fg));\n}\n```\n\n#### Do Not Wrap `<mds-file>` in a Native Anchor or Button\n\nThe host is already focusable (`tabindex=\"0\"`) 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"
|
|
8755
8755
|
},
|
|
8756
8756
|
"props": [
|
|
@@ -10000,8 +10000,8 @@
|
|
|
10000
10000
|
}
|
|
10001
10001
|
],
|
|
10002
10002
|
"usage": {
|
|
10003
|
-
"1. Description": "The `<mds-filter>` web component is a compound container that groups a set of `<mds-filter-item>` chips into a single, scrollable filter bar, coordinating their selection state and exposing the active values as one combined change event. It has no native HTML equivalent: it orchestrates its children rather than rendering a control of its own.\n\n#### Semantic Behavior\n\n- **Compound parent**: Acts as the controller for slotted `<mds-filter-item>` children, driving their state in response to selection events.\n- **Selection coordination**: In single mode it enforces exclusive selection (selecting one deselects the others); in `multiple` mode it keeps every selected child active and tracks how many are selected.\n- **Combined change event**: `mdsFilterChange` fires whenever
|
|
10004
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-filter>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Single-Select Filter Bar\n\nThe canonical form. Slot `<mds-filter-item>` children directly; the parent enforces exclusive selection in single mode - selecting one item deselects all others. Always provide `value` on each item so the `mdsFilterChange` event carries meaningful data.\n\n```html\n<mds-filter label=\"Categoria\">\n <mds-filter-item label=\"Tutti\" value=\"all\"></mds-filter-item>\n <mds-filter-item label=\"Notizie\" value=\"news\"></mds-filter-item>\n <mds-filter-item label=\"Comunicati\" value=\"press\" count=\"14\"></mds-filter-item>\n <mds-filter-item label=\"Aggiornamenti\" value=\"updates\" count=\"3\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Listening to Selection Changes\n\nListen to `mdsFilterChange` on the parent. The event detail carries `value` (comma-joined string of selected `value` attributes) and `children` (the `NodeList` of the items, for advanced inspection).\n\n```html\n<mds-filter id=\"filter-stato\" label=\"Stato\">\n <mds-filter-item label=\"Bozza\" value=\"draft\"></mds-filter-item>\n <mds-filter-item label=\"Pubblicato\" value=\"published\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</mds-filter>\n\n<script>\n document.getElementById('filter-stato').addEventListener('mdsFilterChange', (event) => {\n console.log('Filtro attivo:', event.detail.value);\n });\n</script>\n```\n\n#### Multi-Select Filter Bar\n\nSet `multiple` when filters are additive rather than mutually exclusive. All selected items stay active simultaneously; `mdsFilterChange` fires after each toggle.\n\n```html\n<mds-filter label=\"Etichette\" multiple>\n <mds-filter-item label=\"Urgente\" value=\"urgent\" count=\"2\"></mds-filter-item>\n <mds-filter-item label=\"In revisione\" value=\"review\" count=\"7\"></mds-filter-item>\n <mds-filter-item label=\"Completato\" value=\"done\" count=\"31\"></mds-filter-item>\n <mds-filter-item label=\"Annullato\" value=\"cancelled\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Reset Button\n\nSet `reset` to show a clear-all control whenever at least one item is active. The reset control is hidden when no filter is selected and becomes visible automatically when a selection is made.\n\n```html\n<mds-filter label=\"Tipo documento\" multiple reset>\n <mds-filter-item label=\"PDF\" value=\"pdf\" count=\"5\"></mds-filter-item>\n <mds-filter-item label=\"Word\" value=\"doc\" count=\"12\"></mds-filter-item>\n <mds-filter-item label=\"Immagine\" value=\"image\" count=\"8\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Auto-Reset on Full Selection\n\nUse `auto-reset` together with `multiple` when selecting all items is semantically identical to \"no filter applied\". Once every item is selected, the component clears all selections automatically.\n\n```html\n<mds-filter label=\"Priorita\" multiple auto-reset>\n <mds-filter-item label=\"Alta\" value=\"high\"></mds-filter-item>\n <mds-filter-item label=\"Media\" value=\"medium\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\" value=\"low\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Filter Item with Icon\n\nSupply `icon` on individual `<mds-filter-item>` children to add a glyph alongside the label. The icon slug follows iconsauce conventions;
|
|
10003
|
+
"1. Description": "The `<mds-filter>` web component is a compound container that groups a set of `<mds-filter-item>` chips into a single, scrollable filter bar, coordinating their selection state and exposing the active values as one combined change event. It has no native HTML equivalent: it orchestrates its children rather than rendering a control of its own.\n\n#### Semantic Behavior\n\n- **Compound parent**: Acts as the controller for slotted `<mds-filter-item>` children, driving their state in response to selection events.\n- **Group of toggles**: The host is a `group` named by `label`, and each item is a toggle button whose pressed state follows its selection: a screen reader hears which filters are on and how many results each one shows. Every item is a Tab stop; there is no arrow-key navigation.\n- **Selection coordination**: In single mode it enforces exclusive selection (selecting one deselects the others); in `multiple` mode it keeps every selected child active and tracks how many are selected.\n- **Selection set by the application**: The selection lives on the items' `selected`. Setting or clearing it from the application, or rendering an item already selected, is taken in as after a click: in single mode only the last item set stays selected, the reset button shows or hides, the strip scrolls to the item. No `mdsFilterChange` is emitted for it, and `autoReset` does not apply: the application already knows. Two items `selected` in the markup of a single-mode bar leave the last one selected, as a `<select>` does.\n- **Combined change event**: `mdsFilterChange` fires whenever the user changes the selection (an item, or the reset button), carrying both the `NodeList` of the children and a comma-joined string of the selected items' `value`s.\n- **Reset control**: When `reset` is set, a clear-all button appears once a filter is active, named in the page language (the `lang` of `<html>`) (\"Clear filters\"). A click clears all selections and emits `mdsFilterChange` with an empty `value`. While no filter is active the button is scaled away, out of the tab order and of the accessibility tree; without `reset` it is not rendered at all.\n- **Auto-scroll**: On each selection the bar scrolls horizontally to center the most recently selected item.\n- **Default slot**: The default slot is for `<mds-filter-item>` elements only, not arbitrary text or markup.\n\n#### Properties & Visual Configurations\n\n- **`multiple`** switches the bar from exclusive single-select behavior to allowing several items active at once; choose it when filters are additive rather than mutually exclusive.\n- **`reset`** opts the bar into showing a dedicated clear-all control whenever one or more filters are active.\n- **`autoReset`** automatically clears all selections once every item has been selected - useful in `multiple` mode where \"all selected\" is equivalent to \"no filter applied\".\n",
|
|
10004
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-filter>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Single-Select Filter Bar\n\nThe canonical form. Slot `<mds-filter-item>` children directly; the parent enforces exclusive selection in single mode - selecting one item deselects all others. Always provide `value` on each item so the `mdsFilterChange` event carries meaningful data.\n\n```html\n<mds-filter label=\"Categoria\">\n <mds-filter-item label=\"Tutti\" value=\"all\"></mds-filter-item>\n <mds-filter-item label=\"Notizie\" value=\"news\"></mds-filter-item>\n <mds-filter-item label=\"Comunicati\" value=\"press\" count=\"14\"></mds-filter-item>\n <mds-filter-item label=\"Aggiornamenti\" value=\"updates\" count=\"3\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Listening to Selection Changes\n\nListen to `mdsFilterChange` on the parent. The event detail carries `value` (comma-joined string of selected `value` attributes) and `children` (the `NodeList` of the items, for advanced inspection).\n\n```html\n<mds-filter id=\"filter-stato\" label=\"Stato\">\n <mds-filter-item label=\"Bozza\" value=\"draft\"></mds-filter-item>\n <mds-filter-item label=\"Pubblicato\" value=\"published\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</mds-filter>\n\n<script>\n document.getElementById('filter-stato').addEventListener('mdsFilterChange', (event) => {\n console.log('Filtro attivo:', event.detail.value);\n });\n</script>\n```\n\n#### Multi-Select Filter Bar\n\nSet `multiple` when filters are additive rather than mutually exclusive. All selected items stay active simultaneously; `mdsFilterChange` fires after each toggle.\n\n```html\n<mds-filter label=\"Etichette\" multiple>\n <mds-filter-item label=\"Urgente\" value=\"urgent\" count=\"2\"></mds-filter-item>\n <mds-filter-item label=\"In revisione\" value=\"review\" count=\"7\"></mds-filter-item>\n <mds-filter-item label=\"Completato\" value=\"done\" count=\"31\"></mds-filter-item>\n <mds-filter-item label=\"Annullato\" value=\"cancelled\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Reset Button\n\nSet `reset` to show a clear-all control whenever at least one item is active. The reset control is hidden when no filter is selected and becomes visible automatically when a selection is made. It is named in the page language (\"Clear filters\") and emits `mdsFilterChange` with an empty `value` when it clears the selection.\n\n```html\n<mds-filter label=\"Tipo documento\" multiple reset>\n <mds-filter-item label=\"PDF\" value=\"pdf\" count=\"5\"></mds-filter-item>\n <mds-filter-item label=\"Word\" value=\"doc\" count=\"12\"></mds-filter-item>\n <mds-filter-item label=\"Immagine\" value=\"image\" count=\"8\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Auto-Reset on Full Selection\n\nUse `auto-reset` together with `multiple` when selecting all items is semantically identical to \"no filter applied\". Once every item is selected, the component clears all selections automatically.\n\n```html\n<mds-filter label=\"Priorita\" multiple auto-reset>\n <mds-filter-item label=\"Alta\" value=\"high\"></mds-filter-item>\n <mds-filter-item label=\"Media\" value=\"medium\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\" value=\"low\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Filter Item with Icon\n\nSupply `icon` on individual `<mds-filter-item>` children to add a glyph alongside the label. The icon slug follows iconsauce conventions; the spoken name comes from `label`, or from the icon slug when no label is present (`grid view` for `mi/baseline/grid-view`).\n\n```html\n<mds-filter label=\"Formato\">\n <mds-filter-item label=\"Video\" value=\"video\" icon=\"mi/baseline/videocam\"></mds-filter-item>\n <mds-filter-item label=\"Audio\" value=\"audio\" icon=\"mi/baseline/headset\"></mds-filter-item>\n <mds-filter-item label=\"Testo\" value=\"text\" icon=\"mi/baseline/article\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Pre-Selected Item\n\nSet `selected` on a child at page load to reflect a filter that is already active (e.g. restored from a URL parameter or user preference). The parent picks up the initial state when it loads.\n\n```html\n<mds-filter label=\"Periodo\">\n <mds-filter-item label=\"Oggi\" value=\"today\"></mds-filter-item>\n <mds-filter-item label=\"Settimana corrente\" value=\"week\" selected></mds-filter-item>\n <mds-filter-item label=\"Mese corrente\" value=\"month\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Setting the Selection from the Application\n\nWhen the filters live somewhere else - in the address, in a store, behind a \"Clear filters\" button outside the bar - set `selected` on the items: the bar follows as after the same clicks (single mode, reset button), without emitting `mdsFilterChange`. In a framework, bind `selected` on each item to the state.\n\n```html\n<mds-filter id=\"status\" label=\"Stato\" reset>\n <mds-filter-item label=\"Nuove\" value=\"new\"></mds-filter-item>\n <mds-filter-item label=\"Aperte\" value=\"open\"></mds-filter-item>\n <mds-filter-item label=\"Chiuse\" value=\"closed\"></mds-filter-item>\n</mds-filter>\n<mds-button id=\"clear\" label=\"Rimuovi i filtri\" variant=\"dark\" tone=\"text\"></mds-button>\n```\n\n```js\nconst items = [...document.querySelectorAll('#status mds-filter-item')];\n\n// restore the filter from the address on load\nconst status = new URLSearchParams(location.search).get('status');\nitems.forEach((item) => {\n item.selected = item.value === status;\n});\n\n// clear it from a button outside the bar\ndocument.querySelector('#clear').addEventListener('click', () => {\n items.forEach((item) => {\n item.selected = false;\n });\n});\n```\n\n#### Disabled Item\n\nSet `disabled` on individual `<mds-filter-item>` children to block them: a disabled item leaves the tab order, ignores clicks and keys, is announced as unavailable (`aria-disabled`) and is painted in the disabled text colour.\n\n```html\n<mds-filter label=\"Stato pratica\">\n <mds-filter-item label=\"Aperta\" value=\"open\" count=\"9\"></mds-filter-item>\n <mds-filter-item label=\"In attesa\" value=\"pending\" count=\"2\"></mds-filter-item>\n <mds-filter-item label=\"Chiusa\" value=\"closed\" disabled></mds-filter-item>\n</mds-filter>\n```\n\n#### Styling Customization\n\nStyle the filter bar only through its documented `--mds-filter-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` and the `--magma-radius-*` scale so dark mode, high-contrast modes and the corner geometry keep working.\n\n```css\n.filtri-personalizzati mds-filter {\n --mds-filter-items-background: rgb(var(--magma-wash-strong));\n --mds-filter-items-background-active: rgb(var(--magma-accent-surface));\n --mds-filter-items-radius: var(--magma-radius-md);\n --mds-filter-items-gap: calc(var(--spacing) * 300);\n --mds-filter-wrapper-shadow-color: rgb(var(--magma-accent-border));\n --mds-filter-wrapper-shadow-opacity: 0.2;\n}\n```\n",
|
|
10005
10005
|
"3. Antipattern": "Common incorrect uses of `<mds-filter>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Slot Arbitrary Elements Instead of `mds-filter-item`\n\nThe default slot accepts only `<mds-filter-item>` elements. The parent wires its coordination logic - exclusive selection, scroll-centering, value aggregation - by querying for `mds-filter-item` children. Slotting plain buttons, spans, or any other element breaks all of that coordination.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Tipo\">\n <button>Notizie</button>\n <button>Comunicati</button>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Tipo\">\n <mds-filter-item label=\"Notizie\" value=\"news\"></mds-filter-item>\n <mds-filter-item label=\"Comunicati\" value=\"press\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Use `mds-filter-item` Outside `mds-filter`\n\n`<mds-filter-item>` communicates state upward via the `mdsFilterItemSelect` event, which `<mds-filter>` listens for internally. Used standalone, the item has no parent to coordinate selection, no auto-scroll, and no combined `mdsFilterChange` output.\n\n```html\n<!-- INCORRECT -->\n<div class=\"my-filter-bar\">\n <mds-filter-item label=\"Tutti\" value=\"all\"></mds-filter-item>\n <mds-filter-item label=\"Attivi\" value=\"active\"></mds-filter-item>\n</div>\n\n<!-- CORRECT -->\n<mds-filter>\n <mds-filter-item label=\"Tutti\" value=\"all\"></mds-filter-item>\n <mds-filter-item label=\"Attivi\" value=\"active\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Listen to Native `change` Instead of `mdsFilterChange`\n\n`<mds-filter>` emits the documented `mdsFilterChange` custom event. It contains no native form control, so no `change` or `input` event is ever fired; listening for them produces no result.\n\n```html\n<!-- INCORRECT -->\n<mds-filter id=\"f\" label=\"Stato\">\n <mds-filter-item label=\"Aperto\" value=\"open\"></mds-filter-item>\n</mds-filter>\n<script>\n document.getElementById('f').addEventListener('change', handler);\n</script>\n\n<!-- CORRECT -->\n<mds-filter id=\"f\" label=\"Stato\">\n <mds-filter-item label=\"Aperto\" value=\"open\"></mds-filter-item>\n</mds-filter>\n<script>\n document.getElementById('f').addEventListener('mdsFilterChange', handler);\n</script>\n```\n\n#### Do Not Set Boolean Props to the String `\"false\"`\n\n`auto-reset`, `multiple`, and `reset` are boolean attributes: remove the attribute entirely to deactivate it, as for every boolean. The runtime happens to read the string `\"false\"` as `false`, but the attribute stays in the markup until the component renders, and HTML, `[multiple]` selectors and `hasAttribute()` read a present attribute as set.\n\n```html\n<!-- INCORRECT -->\n<mds-filter multiple=\"false\" reset=\"false\" label=\"Tipo\">\n <mds-filter-item label=\"Tutti\" value=\"all\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Tipo\">\n <mds-filter-item label=\"Tutti\" value=\"all\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Use `auto-reset` Without `multiple`\n\n`auto-reset` is meaningful only in `multiple` mode - it triggers when all items are simultaneously selected. In single-select mode only one item can ever be active, so the \"all selected\" condition is never reached and `auto-reset` has no effect.\n\n```html\n<!-- INCORRECT -->\n<mds-filter auto-reset label=\"Priorita\">\n <mds-filter-item label=\"Alta\" value=\"high\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\" value=\"low\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter multiple auto-reset label=\"Priorita\">\n <mds-filter-item label=\"Alta\" value=\"high\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\" value=\"low\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Omit `value` on `mds-filter-item`\n\nThe `mdsFilterChange` event's `value` field is a comma-joined string of the selected items' `value` attributes. Items without a `value` contribute an empty string to the output, making the combined value ambiguous and hard to parse in application code.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Formato\">\n <mds-filter-item label=\"PDF\"></mds-filter-item>\n <mds-filter-item label=\"Word\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Formato\">\n <mds-filter-item label=\"PDF\" value=\"pdf\"></mds-filter-item>\n <mds-filter-item label=\"Word\" value=\"doc\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Customize Via Undocumented Shadow Selectors\n\nThe supported customization surface for `<mds-filter>` is the documented `--mds-filter-*` CSS custom properties. Piercing the shadow DOM via `>>>` or undocumented `::part()` names couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-filter >>> .items {\n background: white;\n}\nmds-filter::part(items-wrapper) {\n border: 2px solid red;\n}\n\n/* CORRECT */\nmds-filter {\n --mds-filter-items-background: rgb(var(--magma-wash-strong));\n --mds-filter-wrapper-shadow-color: rgb(var(--magma-accent-border));\n}\n```\n"
|
|
10006
10006
|
},
|
|
10007
10007
|
"props": [
|
|
@@ -10225,8 +10225,8 @@
|
|
|
10225
10225
|
"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.",
|
|
10226
10226
|
"docsTags": [],
|
|
10227
10227
|
"usage": {
|
|
10228
|
-
"1. Description": "The `<mds-filter-item>` web component is a single selectable option inside the [`<mds-filter>`](../mds-filter/AGENTS.md) container of the Magma Design System. It renders as
|
|
10229
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-filter-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Filter Group\n\nThe canonical form. Place one or more `<mds-filter-item>` elements as direct children of `<mds-filter>`. Every item requires a `label` (the visible text) and a `value` (the machine-readable token emitted by the parent's `mdsFilterChange` event).\n\n```html\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n <mds-filter-item label=\"In attesa\" value=\"pending\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Pre-selecting an Item on Load\n\nSet `selected` on an item in the initial markup to make it active before any user interaction. The parent reads `selected` on mount and reflects the aggregated state correctly.\n\n```html\n<mds-filter label=\"Categoria\">\n <mds-filter-item label=\"Tutti\" value=\"all\" selected></mds-filter-item>\n <mds-filter-item label=\"Notizie\" value=\"news\"></mds-filter-item>\n <mds-filter-item label=\"Eventi\" value=\"events\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Count Badge\n\nPass a `count` string to show how many results each filter would yield. Use it when the number is meaningful to the user; omit it for purely categorical filters to keep the UI uncluttered.\n\n```html\n<mds-filter label=\"Priorita\">\n <mds-filter-item label=\"Alta\" value=\"high\" count=\"12\"></mds-filter-item>\n <mds-filter-item label=\"Media\" value=\"medium\" count=\"34\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\" value=\"low\" count=\"5\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Icon-Only Item\n\nOmit `label` and provide only `icon`.
|
|
10228
|
+
"1. Description": "The `<mds-filter-item>` web component is a single selectable option inside the [`<mds-filter>`](../mds-filter/AGENTS.md) container of the Magma Design System. It renders as a toggle button (icon, label, and an optional count badge) and acts as the toggleable unit that drives the parent's filter selection - it has no standalone HTML primitive equivalent.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-filter-item>` must be a direct slot child of `<mds-filter>`; it is not used standalone and should not be mixed with other child types.\n- **Self-toggling + event**: Clicking (or activating via the keyboard) flips `selected` and emits `mdsFilterItemSelect` with `{ id, selected }`. The `id` is the one the parent assigns on load (`item-0`, `item-1`, ...), replacing any `id` set in the markup. The parent enforces single vs. multiple selection and re-emits `mdsFilterChange` with the aggregated value list.\n- **State owned with the parent**: `selected` doubles as a styling hook and as the flag the parent reads/writes - in single-select mode the parent clears the other items' selection, and on reset it clears the whole group. The parent also follows a `selected` set by the application, without emitting `mdsFilterChange`.\n- **Toggle button**: The host is a `button` whose `aria-pressed` follows `selected`. Its name is the `label` followed by the `count` as a number of results in the page language (the `lang` of `<html>`): \"Nuove, 11 results\" in English, \"Nuove, 11 risultati\" in Italian. An `aria-label` written on the host by the author stays.\n- **Keyboard activation**: Enter (and numpad Enter) and Space activate the item like a pointer click.\n- **Focus management**: The item is focusable unless `disabled`, in which case it drops out of the tab order.\n\n#### Properties & Visual Configurations\n\n- **`selected`**: The selection state of the item. Set it on initial markup to pre-select a filter, or at runtime from the application (a filter restored from the address, a clear button outside the bar): the parent follows, in single mode clearing the others.\n- **`value`**: The form/data value contributed to the parent's aggregated `mdsFilterChange` payload when the item is selected. Provide a meaningful value distinct from the human-readable `label`.\n- **`count`**: An optional badge showing how many results the filter would yield. Use it only when the count is meaningful to the user; omit it for purely categorical filters.\n- **`icon`**: Optional leading icon (an icon name string). Without a `label` the item is named after the last segment of the slug (`map` for `mi/baseline/map`); give it an `aria-label` of your own when the slug does not say what the filter does.\n- **`disabled`**: Blocks the item: it leaves the tab order, ignores clicks and keys, is announced as unavailable (`aria-disabled`) and is painted in the disabled text colour.\n",
|
|
10229
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-filter-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Filter Group\n\nThe canonical form. Place one or more `<mds-filter-item>` elements as direct children of `<mds-filter>`. Every item requires a `label` (the visible text) and a `value` (the machine-readable token emitted by the parent's `mdsFilterChange` event).\n\n```html\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n <mds-filter-item label=\"In attesa\" value=\"pending\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Pre-selecting an Item on Load\n\nSet `selected` on an item in the initial markup to make it active before any user interaction. The parent reads `selected` on mount and reflects the aggregated state correctly.\n\n```html\n<mds-filter label=\"Categoria\">\n <mds-filter-item label=\"Tutti\" value=\"all\" selected></mds-filter-item>\n <mds-filter-item label=\"Notizie\" value=\"news\"></mds-filter-item>\n <mds-filter-item label=\"Eventi\" value=\"events\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Count Badge\n\nPass a `count` string to show how many results each filter would yield. Use it when the number is meaningful to the user; omit it for purely categorical filters to keep the UI uncluttered.\n\n```html\n<mds-filter label=\"Priorita\">\n <mds-filter-item label=\"Alta\" value=\"high\" count=\"12\"></mds-filter-item>\n <mds-filter-item label=\"Media\" value=\"medium\" count=\"34\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\" value=\"low\" count=\"5\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Icon-Only Item\n\nOmit `label` and provide only `icon`. Without a label the item is named after the last segment of the icon slug (`grid view` for `mi/baseline/grid-view`); an `aria-label` of your own takes its place and stays. Use a recognizable icon so the purpose is clear without text, and give each item an `aria-label` when the slug does not say what it filters.\n\n```html\n<mds-filter label=\"Vista\">\n <mds-filter-item aria-label=\"Griglia\" icon=\"mi/baseline/grid-view\" value=\"grid\"></mds-filter-item>\n <mds-filter-item aria-label=\"Elenco\" icon=\"mi/baseline/view-list\" value=\"list\"></mds-filter-item>\n <mds-filter-item aria-label=\"Mappa\" icon=\"mi/baseline/map\" value=\"map\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Item with Icon and Label\n\nCombine `icon` and `label` for a filter item that pairs a glyph with a text description.\n\n```html\n<mds-filter label=\"Tipo documento\">\n <mds-filter-item icon=\"mi/baseline/picture-as-pdf\" label=\"PDF\" value=\"pdf\"></mds-filter-item>\n <mds-filter-item icon=\"mi/baseline/image\" label=\"Immagini\" value=\"image\"></mds-filter-item>\n <mds-filter-item icon=\"mi/baseline/video-library\" label=\"Video\" value=\"video\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Multiple Selection\n\nAdd `multiple` to `<mds-filter>` to allow several items to be selected at the same time. The parent aggregates the selected `value`s into a comma-separated string and emits it via `mdsFilterChange`.\n\n```html\n<mds-filter label=\"Settore\" multiple>\n <mds-filter-item label=\"Sanita\" value=\"health\"></mds-filter-item>\n <mds-filter-item label=\"Istruzione\" value=\"education\"></mds-filter-item>\n <mds-filter-item label=\"Trasporti\" value=\"transport\"></mds-filter-item>\n <mds-filter-item label=\"Ambiente\" value=\"environment\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Listening for Selection Events\n\nListen to `mdsFilterItemSelect` on a single item for per-item reactions, or to `mdsFilterChange` on the parent for the aggregated selection. The event detail for `mdsFilterItemSelect` is `{ id: string, selected: boolean }`.\n\n```html\n<mds-filter id=\"tipo-filter\" label=\"Tipo\">\n <mds-filter-item label=\"Bozza\" value=\"draft\"></mds-filter-item>\n <mds-filter-item label=\"Pubblicato\" value=\"published\"></mds-filter-item>\n</mds-filter>\n\n<script>\n document.getElementById('tipo-filter').addEventListener('mdsFilterChange', (e) => {\n console.log('Valori selezionati:', e.detail.value);\n });\n</script>\n```\n\n#### Reset Affordance\n\nAdd `reset` to `<mds-filter>` to show an automatic reset button when at least one item is active. The button is rendered by the parent internally - no extra `<mds-filter-item>` is needed - and named in the page language (\"Clear filters\").\n\n```html\n<mds-filter label=\"Regione\" reset>\n <mds-filter-item label=\"Nord\" value=\"north\"></mds-filter-item>\n <mds-filter-item label=\"Centro\" value=\"center\"></mds-filter-item>\n <mds-filter-item label=\"Sud\" value=\"south\"></mds-filter-item>\n</mds-filter>\n```\n\n#### CSS Custom Properties for the Count Badge\n\nCustomize the count badge colors through the four documented `--mds-filter-item-count-*` CSS custom properties. Set them on the host element or on a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))`.\n\n```css\n.priority-filter mds-filter-item {\n --mds-filter-item-count-background-default: rgb(var(--magma-wash-strong));\n --mds-filter-item-count-color-default: rgb(var(--magma-text-default));\n --mds-filter-item-count-background-selected: rgb(var(--magma-accent-emphasis));\n --mds-filter-item-count-color-selected: rgb(var(--magma-accent-on-emphasis));\n}\n```\n",
|
|
10230
10230
|
"3. Antipattern": "Common incorrect uses of `<mds-filter-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-filter-item>` Outside `<mds-filter>`\n\n`<mds-filter-item>` is a compound child component. Without its parent it has no selection management, no auto-scroll, and no `mdsFilterChange` aggregation. Always wrap it in `<mds-filter>`.\n\n```html\n<!-- INCORRECT -->\n<div class=\"my-filters\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</div>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Set `selected=\"false\"` to Deselect\n\n`selected` is a boolean prop: remove the attribute entirely to deselect, as for every boolean. The runtime happens to read the string `\"false\"` as `false`, but the attribute stays in the markup until the component renders, and HTML, `[selected]` selectors and `hasAttribute()` read a present attribute as set.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\" selected=\"false\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Omit `value`\n\n`value` is the machine-readable token the parent aggregates into `mdsFilterChange`. Without it the parent's event payload is empty or meaningless for consumers - always provide a distinct, meaningful value.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Priorita\">\n <mds-filter-item label=\"Alta\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Priorita\">\n <mds-filter-item label=\"Alta\" value=\"high\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\" value=\"low\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Slot Content Inside `<mds-filter-item>`\n\n`<mds-filter-item>` has no publicly documented default or named slots. Icon, label, and count are all props. Slotting arbitrary HTML has no effect - use the dedicated props instead.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Formato\">\n <mds-filter-item value=\"pdf\">\n <mds-icon name=\"mi/baseline/picture-as-pdf\"></mds-icon>\n PDF\n </mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Formato\">\n <mds-filter-item icon=\"mi/baseline/picture-as-pdf\" label=\"PDF\" value=\"pdf\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Listen for Native `click` Instead of `mdsFilterItemSelect`\n\nThe component handles its own toggle internally and emits `mdsFilterItemSelect` when selection changes. A native `click` listener added before the component has loaded runs before the internal toggle (listeners run in the order they were added), so it reads the old `selected` state.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n<script>\n document.querySelector('mds-filter-item[value=\"active\"]').addEventListener('click', (e) => {\n console.log('selected?', e.target.selected); // state not yet updated\n });\n</script>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n<script>\n document.querySelector('mds-filter-item[value=\"active\"]').addEventListener('mdsFilterItemSelect', (e) => {\n console.log('selected:', e.detail.selected);\n });\n</script>\n```\n\n#### Do Not Customize via Undocumented Shadow Parts or Internal Selectors\n\nThe supported customization surface is the four `--mds-filter-item-count-*` CSS custom properties. Targeting shadow internals via `::part()`, `>>>`, or other selectors couples code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-filter-item >>> .count {\n border-radius: 4px;\n}\nmds-filter-item::part(count) {\n background: red;\n}\n\n/* CORRECT */\nmds-filter-item {\n --mds-filter-item-count-background-default: rgb(var(--magma-accent-surface-hover));\n --mds-filter-item-count-color-default: rgb(var(--magma-accent-fg));\n}\n```\n"
|
|
10231
10231
|
},
|
|
10232
10232
|
"props": [
|
|
@@ -10241,7 +10241,7 @@
|
|
|
10241
10241
|
"mutable": false,
|
|
10242
10242
|
"attr": "count",
|
|
10243
10243
|
"reflectToAttr": true,
|
|
10244
|
-
"docs": "Shows the number of items will be filtered by the component",
|
|
10244
|
+
"docs": "Shows the number of items will be filtered by the component, also read out after the label\nas a number of results",
|
|
10245
10245
|
"docsTags": [],
|
|
10246
10246
|
"values": [
|
|
10247
10247
|
{
|
|
@@ -10959,7 +10959,7 @@
|
|
|
10959
10959
|
}
|
|
10960
10960
|
],
|
|
10961
10961
|
"usage": {
|
|
10962
|
-
"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 only records the opened state: it renders nothing and does not open or close the drawer, which is driven by `setOpened()` on the surrounding `mds-header`.\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\nInside `mds-header` both are written by the header from its own `menu` and `nav` when it loads, replacing the values set on the bar: set them on `mds-header` there.\n",
|
|
10962
|
+
"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, icon-only and named in the page language (the `lang` of `<html>`) (\"Open menu\").\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 only records the opened state: it renders nothing and does not open or close the drawer, which is driven by `setOpened()` on the surrounding `mds-header`.\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\nInside `mds-header` both are written by the header from its own `menu` and `nav` when it loads, replacing the values set on the bar: set them on `mds-header` there.\n",
|
|
10963
10963
|
"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 shared component rules in [`agents/conventions.md`](../../../../agents/conventions.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\"></mds-img>\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/AGENTS.md). 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 (inside `mds-header`, set `menu` and `nav` on `mds-header`: it overwrites the bar's values when it loads). 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\"></mds-img>\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\"></mds-img>\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\nThe bar's own `setOpened(isOpened)` only records the state and renders nothing. To open or close the drawer from external code - for instance after route navigation in a single-page app - call `setOpened` on the surrounding `mds-header`.\n\n```html\n<mds-header id=\"main-header\">\n <mds-header-bar>\n <mds-text typography=\"h6\">Dashboard</mds-text>\n </mds-header-bar>\n <div slot=\"menu\">\n <mds-button label=\"Pratiche\" variant=\"dark\" tone=\"text\"></mds-button>\n </div>\n</mds-header>\n\n<script>\n // Close the drawer after the user selects a menu item\n const header = document.getElementById('main-header');\n header.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 semantic color role wrapped with `rgb(var(--magma-<role>))` so dark-mode works automatically.\n\n```css\nmds-header-bar {\n --mds-header-bar-hamburger-color: rgb(var(--magma-accent-fg));\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: calc(var(--spacing) * 600);\n}\n\n/* Visually highlight the hamburger button in a branded theme */\nmds-header-bar::part(hamburger) {\n border-radius: var(--magma-radius-md);\n background-color: rgb(var(--magma-accent-surface));\n}\n```\n",
|
|
10964
10964
|
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - 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/AGENTS.md). 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\"></mds-img>\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\"></mds-img>\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\"></mds-img>\n <mds-button slot=\"nav\" variant=\"dark\" tone=\"text\">Servizi</mds-button>\n</mds-header-bar>\n\n<!-- CORRECT (at least one region stays visible) -->\n<mds-header-bar menu=\"none\" nav=\"all\">\n <mds-img src=\"./logo.svg\"></mds-img>\n <mds-button slot=\"nav\" variant=\"dark\" tone=\"text\">Servizi</mds-button>\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(--magma-accent-fg));\n}\nmds-header-bar::part(hamburger) {\n background-color: rgb(var(--magma-wash-base));\n}\n```\n\n#### Do Not Listen to `click` on the Hamburger Instead of `mdsHeaderBarOpen`\n\nA `click` listener on the host fires for every click inside the bar (logo, nav buttons), not only on the hamburger. Use the documented `mdsHeaderBarOpen` event, which bubbles and fires only when the hamburger is pressed.\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 not validated: any value other than `none` shows the region on every viewport, as `all` does, 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"
|
|
10965
10965
|
},
|
|
@@ -11176,8 +11176,8 @@
|
|
|
11176
11176
|
"filePath": "src/components/mds-help/mds-help.tsx",
|
|
11177
11177
|
"encapsulation": "shadow",
|
|
11178
11178
|
"tag": "mds-help",
|
|
11179
|
-
"readme": "# mds-help\n\
|
|
11180
|
-
"docs": "This
|
|
11179
|
+
"readme": "# mds-help\n\n\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
|
|
11180
|
+
"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.",
|
|
11181
11181
|
"docsTags": [
|
|
11182
11182
|
{
|
|
11183
11183
|
"name": "slot",
|
|
@@ -11404,7 +11404,7 @@
|
|
|
11404
11404
|
}
|
|
11405
11405
|
],
|
|
11406
11406
|
"usage": {
|
|
11407
|
-
"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. Browsers without the `scrollend` event get no arrows: the component clears `controls` there.\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 smallest 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 [`agents/variants.md`](../../../../agents/variants.md); appearance is tuned entirely through its CSS custom properties (see [`AGENTS.md`](AGENTS.md)).\n",
|
|
11407
|
+
"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, icon-only and named in the page language (the `lang` of `<html>`) (\"Scroll back\", \"Scroll forward\"); each advances the scroll position to the next/previous item not fully in the viewport. Browsers without the `scrollend` event get no arrows: the component clears `controls` there.\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 smallest 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 [`agents/variants.md`](../../../../agents/variants.md); appearance is tuned entirely through its CSS custom properties (see [`AGENTS.md`](AGENTS.md)).\n",
|
|
11408
11408
|
"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 shared component rules in [`agents/conventions.md`](../../../../agents/conventions.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 the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.sezione-evidenza mds-horizontal-scroll {\n --mds-horizontal-scroll-dot-background: rgb(var(--magma-accent-emphasis));\n --mds-horizontal-scroll-dot-area-background: rgb(var(--magma-accent-surface-hover));\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: var(--magma-radius-3xs);\n --mds-horizontal-scroll-scrollbar-thumb-background: rgb(var(--magma-accent-emphasis));\n --mds-horizontal-scroll-scrollbar-track-background: rgb(var(--magma-wash-strong));\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: calc(var(--spacing) * 800);\n}\n```\n",
|
|
11409
11409
|
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - 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 `\"\"`) gives an empty string, which renders no arrows at all - the opposite of what a bare boolean attribute suggests. 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`: the arrows end up hidden only because no breakpoint rule matches it, and a type check rejects it.\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(--magma-accent-emphasis));\n}\nmds-horizontal-scroll::part(content) {\n padding-block: calc(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"
|
|
11410
11410
|
},
|
|
@@ -11689,8 +11689,8 @@
|
|
|
11689
11689
|
"filePath": "src/components/mds-icon/mds-icon.tsx",
|
|
11690
11690
|
"encapsulation": "shadow",
|
|
11691
11691
|
"tag": "mds-icon",
|
|
11692
|
-
"readme": "# mds-icon\n\n
|
|
11693
|
-
"docs": "",
|
|
11692
|
+
"readme": "# mds-icon\n\n\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
|
|
11693
|
+
"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.",
|
|
11694
11694
|
"docsTags": [
|
|
11695
11695
|
{
|
|
11696
11696
|
"name": "part",
|
|
@@ -12346,12 +12346,12 @@
|
|
|
12346
12346
|
"filePath": "src/components/mds-input/mds-input.tsx",
|
|
12347
12347
|
"encapsulation": "shadow",
|
|
12348
12348
|
"tag": "mds-input",
|
|
12349
|
-
"readme": "# mds-input\n\n
|
|
12350
|
-
"docs": "",
|
|
12349
|
+
"readme": "# mds-input\n\n\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
|
|
12350
|
+
"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.",
|
|
12351
12351
|
"docsTags": [],
|
|
12352
12352
|
"usage": {
|
|
12353
|
-
"1. Description": "The `<mds-input>` web component is the primary single- and multi-line text entry control of the Magma Design System. It wraps a native `<input>` (or `<textarea>` when `type=\"textarea\"`) and layers on form association, validation, inline tips, iconography, password masking, numeric steppers, datalist suggestions and speech-to-text dictation.\n\n#### Semantic Behavior\n\n- **Form association**: The component reports its value to the surrounding `<form>`, so it submits natively. On `disabled` the reported value is cleared. A form reset brings back the value the field had at load, both shown and submitted, and drops the `'success'` or `'error'` look of a past blur, like a native input.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **Form validity**: The validators below also decide the validity reported to the form, on every change of the value or of the rules: like a native control, an invalid field matches `:invalid` and stops the submit, the browser shows a message in the page language next to the field and focuses it, and the field switches to `'error'` as on blur. Disabled and read-only fields are left out, and `novalidate` on the `<form>` turns the check off. `type=\"email\"` and `type=\"url\"` check the format of the value as a native input does.\n- **Validation on blur**: Validation runs when the field loses focus (and re-runs on input once invalid). It drives the `variant` automatically to `'success'` or `'error'`, emits `mdsInputValidation` with the boolean result, and reverts to `'primary'` when an optional field is emptied.\n- **Type-aware validators**: The active validator set is derived from `type` - `email` and `url` install the format validators of the native types, `cf` the codice fiscale format and length validators, `isbn` a checksum validator, `piva` the partita IVA one (11 digits, the last one the check digit) and `cc` the card number one (13 to 19 digits, in groups split by spaces or dashes, that pass the Luhn check); no type applies an input mask, while `required`, `min`/`max` (any number, `0` included), `minlength`/`maxlength` and `pattern` add the corresponding constraint validators. As on a native input, `pattern` has to match the whole value, an expression that does not compile sets no rule, and `number`, `date`, `time` and `textarea` ignore it. The set is rebuilt whenever one of these props changes, also after load, as with the React wrappers under SSR: a pristine field only updates its required tip, a field already validated on blur is validated again. Custom validators can be attached at runtime through the `addValidator`/`removeValidator`/`hasValidator`/`getErrors` methods.\n- **Disabled / read-only tips**: `disabled` and `readonly` surface a persistent top tip describing the state; read-only fields also auto-select their text on focus.\n- **Character counter**: When `maxlength` is set a bottom counter tip shows `current / max` and shifts through fullness variants as the value approaches the limit. A `maxlength` of `0` or less is treated as unset.\n- **Password masking**: With `type=\"password\"` a toggle button reveals/hides the value; it is disabled with the field.\n- **Number steppers**: With `type=\"number\"` increment/decrement buttons are rendered; their placement follows `controlsLayout` and their glyphs follow `controlsIcon`. They are disabled on a disabled or read-only field, like the spin buttons of a native one.\n- **Speech-to-text**: When `mic` is set a dictation button transcribes speech into the value, replacing what was there, and emits `mdsInputSpeechEnd` when the user stops the dictation; when the Web Speech API is unavailable the button switches to an error state and the value is left as it is. The dictation button is disabled on a disabled or read-only field, which the user cannot change, and a dictation in progress stops, emitting `mdsInputSpeechEnd`, when the field becomes so.\n- **Emitted events**: `mdsInputChange` carries the new value, `mdsInputKeydown` fires on every key pressed in the field with the native `KeyboardEvent` as detail (before the value changes: read the value from `mdsInputChange`), and `mdsInputFocus`/`mdsInputBlur` fire on focus transitions.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` ladder (color role) is defined in [`agents/variants.md`](../../../../agents/variants.md); `<mds-input>` consumes it for both intent styling and validation feedback, but does not expose a `tone` prop. It accepts `primary` (default), `ai`, `info`, `success`, `warning` and `error`.\n\n- **`type`** selects both the rendered control and the validation profile: it covers the native HTML types plus format types (`'cf'`, `'piva'`, `'isbn'`, `'cc'`) and switches the host to a multi-line `<textarea>` for `'textarea'`.\n- **`variant=\"ai\"`** auto-assigns the AI chatbot icon when no `icon` is otherwise provided, signposting AI-assisted fields.\n\n#### Other behavioral props\n\n- **`icon`** is an SVG filename slug from the Magma icon library shown at the leading (left) edge of the field; it is suppressed while `await` is active, since the spinner takes its place.\n- **`controlsLayout`** chooses between stacked (`'vertical'`) and split (`'horizontal'`) stepper buttons, and **`controlsIcon`** picks arrow vs. plus/minus glyphs - both apply only to `type=\"number\"`.\n- **`datalist`** supplies suggestion options for `type=\"search\"` style autocompletion.\n- **`tip`** renders inline helper text below the field, and **`typography`** selects the field's text scale.\n",
|
|
12354
|
-
"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 [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Text Input\n\nThe simplest form: set `name` for form participation and `placeholder` for a visual hint. Wrap the component in [`mds-input-field`](../mds-input-field/AGENTS.md) to add a visible label and associated tip.\n\n```html\n<mds-input\n name=\"cognome\"\n placeholder=\"Inserisci il tuo cognome\"\n></mds-input>\n```\n\n#### Required Field with `tip` Helper Text\n\nUse `required` to validate that the field is not empty and `tip` to explain the constraint. The component surfaces a top-tip when focused and drives `variant` to `'error'` or `'success'` on blur. When the field collects the user's own data, set the matching `autocomplete` token (`email`, `given-name`, `tel`, ...) so browsers can identify its purpose (WCAG 2.1 SC 1.3.5) and offer autofill; without it the component default `autocomplete=\"off\"` applies.\n\n```html\n<mds-input\n name=\"email\"\n type=\"email\"\n autocomplete=\"email\"\n placeholder=\"nome@esempio.it\"\n required\n tip=\"Inserisci un indirizzo email valido\"\n></mds-input>\n```\n\n#### Textarea for Multi-line Content\n\nSet `type=\"textarea\"` to render a `<textarea>` instead of a single-line `<input>`. Use the `--mds-input-textarea-*` custom properties to control height and resize behaviour.\n\n```html\n<mds-input\n name=\"descrizione\"\n type=\"textarea\"\n placeholder=\"Descrivi il problema...\"\n maxlength=\"500\"\n></mds-input>\n```\n\n#### Character Counter via `maxlength`\n\nWhen `maxlength` is set the component renders a live `current / max` counter below the field. The counter shifts through fullness variants as the limit approaches. A value of `0` or less is treated as unset.\n\n```html\n<mds-input\n name=\"titolo\"\n placeholder=\"Titolo dell'articolo\"\n maxlength=\"120\"\n></mds-input>\n```\n\n#### Numeric Input with Steppers\n\nSet `type=\"number\"` to enable built-in increment/decrement buttons. Use `controlsLayout` to choose between stacked (`'vertical'`, default) and split (`'horizontal'`) placement, and `controlsIcon` to pick arrow vs. plus/minus glyphs. Use `min`, `max`, and `step` to constrain the legal range.\n\n```html\n<!-- Stacked (default) - arrow glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"1\"\n max=\"99\"\n step=\"1\"\n placeholder=\"1\"\n></mds-input>\n\n<!-- Horizontal split - arithmetic glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"0\"\n max=\"100\"\n controls-layout=\"horizontal\"\n controls-icon=\"arithmetic\"\n placeholder=\"0\"\n></mds-input>\n```\n\n#### Password Input\n\nSet `type=\"password\"` to render a masked field with a built-in visibility toggle. The component renders a custom dot-mask overlay and a show/hide button - no extra wiring is needed. Always set `autocomplete` to `new-password` (sign-up, password change) or `current-password` (login): the component default is `autocomplete=\"off\"`, which browsers and password managers ignore on credential fields, but the explicit token is what lets them pair the password with its username field and fill or generate the right value.\n\n```html\n<mds-input\n name=\"password\"\n type=\"password\"\n autocomplete=\"new-password\"\n placeholder=\"Scegli una password\"\n required\n></mds-input>\n```\n\n#### Login Form\n\nPair a username field carrying `autocomplete=\"username\"` with a password field carrying `autocomplete=\"current-password\"` inside a `<form>`, and submit through `<mds-button type=\"submit\">`. The native fields live in the Shadow DOM of each `<mds-input>`: among the password managers tested, Bitwarden, LastPass, Chrome and Edge detect and fill them, Firefox's built-in manager and KeePassXC-Browser do not (they only look at the light DOM).\n\n```html\n<form action=\"/login\" method=\"post\">\n <mds-input-field label=\"Email\">\n <mds-input name=\"username\" type=\"email\" autocomplete=\"username\" required></mds-input>\n </mds-input-field>\n <mds-input-field label=\"Password\">\n <mds-input name=\"password\" type=\"password\" autocomplete=\"current-password\" required></mds-input>\n </mds-input-field>\n\n <mds-button type=\"submit\" label=\"Accedi\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Italian-Specific Masked Types\n\n`type=\"cf\"` installs the codice fiscale format and length validators and `type=\"isbn\"` a checksum validator. `type=\"piva\"` accepts 11 digits whose last one is the check digit, without the `IT` prefix or spaces, and `type=\"cc\"` 13 to 19 digits, in groups split by spaces or dashes, that pass the Luhn check of card numbers. A value that breaks the format stops the submit of the form. No type applies a keyboard mask.\n\n```html\n<mds-input name=\"codice_fiscale\" type=\"cf\" placeholder=\"RSSMRA80A01H501Z\"></mds-input>\n<mds-input name=\"partita_iva\" type=\"piva\" placeholder=\"01234567890\"></mds-input>\n```\n\n#### Search Input with Datalist\n\nUse `type=\"search\"` combined with the `datalist` prop to offer autocomplete suggestions from a fixed list. The list is rendered inside the shadow DOM and wired automatically.\n\n```html\n<mds-input\n name=\"comune\"\n type=\"search\"\n placeholder=\"Cerca comune...\"\n></mds-input>\n```\n\n```javascript\n// Pass suggestions as a JavaScript array\ndocument.querySelector('mds-input').datalist = ['Roma', 'Milano', 'Napoli', 'Torino'];\n```\n\n#### Icon Decoration\n\nThe `icon` prop renders an SVG slug from the Magma icon library at the leading edge of the field. The icon is suppressed while `await` is active and the spinner takes its place.\n\n```html\n<mds-input\n name=\"cerca\"\n type=\"search\"\n icon=\"mi/baseline/search\"\n placeholder=\"Cerca...\"\n></mds-input>\n```\n\n#### AI-Assisted Field\n\nSet `variant=\"ai\"` to signal an AI-powered field. When no `icon` prop is present, the component auto-assigns the AI chatbot icon.\n\n```html\n<mds-input\n name=\"prompt\"\n type=\"text\"\n variant=\"ai\"\n placeholder=\"Chiedi qualcosa all'assistente...\"\n></mds-input>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while an async operation (e.g. a lookup) is in flight. The component renders an inline spinner in place of the icon. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-input name=\"codice\" placeholder=\"Verifica in corso...\" await></mds-input>\n```\n\n#### Speech-to-Text Dictation\n\nSet the `mic` boolean attribute to render a dictation button. Starting a dictation clears the current value and writes the recognized speech in its place; the component emits `mdsInputSpeechEnd` when the user stops the dictation. If the Web Speech API is unavailable the button switches to an error state and the value is kept.\n\n```html\n<mds-input\n name=\"note_vocali\"\n type=\"text\"\n mic\n placeholder=\"Parla o scrivi...\"\n></mds-input>\n```\n\n#### Listening to Events\n\nListen for `mdsInputChange` instead of native `input` or `change`: `change` does not cross the shadow boundary, and `input` reports only typing, not the values set by the steppers, the dictation or a script.\n\n```javascript\ndocument.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {\n console.log(e.detail.value);\n});\n\ndocument.querySelector('mds-input').addEventListener('mdsInputValidation', (e) => {\n console.log('valido:', e.detail);\n});\n```\n\n#### Form Participation\n\n`<mds-input>` is form-associated. It submits natively inside a `<form>`; set `name` so the value is included in form data. Its validation is reported to the form too: an empty `required` field, or one that breaks another rule, stops the submit like a native input and shows the error. Add `novalidate` to the `<form>` when your own code validates on submit. A reset brings every field back to its value at load and to its pristine look.\n\n```html\n<form action=\"/salva\" method=\"post\">\n <mds-input name=\"nome\" type=\"text\" placeholder=\"Nome\" required></mds-input>\n <mds-input name=\"cognome\" type=\"text\" placeholder=\"Cognome\" required></mds-input>\n <mds-input name=\"email\" type=\"email\" placeholder=\"Email\" required></mds-input>\n\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n</form>\n```\n\n#### Read-Only Display\n\nUse `readonly` when the value should be visible but not editable. A persistent top tip describes the state, and the field text is auto-selected on focus for easy copying.\n\n```html\n<mds-input\n name=\"codice_riferimento\"\n value=\"REF-2024-00123\"\n readonly\n></mds-input>\n```\n\n#### Styling Customization\n\nStyle the input only through its documented `--mds-input-*` CSS custom properties. Set them on the host or a parent selector. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.search-bar mds-input {\n --mds-input-background: rgb(var(--magma-wash-base));\n --mds-input-placeholder-default-color: rgb(var(--magma-text-disabled));\n --mds-input-icon-color: rgb(var(--magma-accent-fg));\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",
|
|
12353
|
+
"1. Description": "The `<mds-input>` web component is the primary single- and multi-line text entry control of the Magma Design System. It wraps a native `<input>` (or `<textarea>` when `type=\"textarea\"`) and layers on form association, validation, inline tips, iconography, password masking, numeric steppers, datalist suggestions and speech-to-text dictation.\n\n#### Semantic Behavior\n\n- **Form association**: The component reports its value to the surrounding `<form>`, so it submits natively. On `disabled` the reported value is cleared. A form reset brings back the value the field had at load, both shown and submitted, and drops the `'success'` or `'error'` look of a past blur, like a native input.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **Form validity**: The validators below also decide the validity reported to the form, on every change of the value or of the rules: like a native control, an invalid field matches `:invalid` and stops the submit, the browser shows a message in the page language next to the field and focuses it, and the field switches to `'error'` as on blur. Disabled and read-only fields are left out, and `novalidate` on the `<form>` turns the check off. `type=\"email\"` and `type=\"url\"` check the format of the value as a native input does.\n- **Validation on blur**: Validation runs when the field loses focus (and re-runs on input once invalid). It drives the `variant` automatically to `'success'` or `'error'`, emits `mdsInputValidation` with the boolean result, and reverts to `'primary'` when an optional field is emptied.\n- **Type-aware validators**: The active validator set is derived from `type` - `email` and `url` install the format validators of the native types, `cf` the codice fiscale format and length validators, `isbn` a checksum validator, `piva` the partita IVA one (11 digits, the last one the check digit) and `cc` the card number one (13 to 19 digits, in groups split by spaces or dashes, that pass the Luhn check); no type applies an input mask, while `required`, `min`/`max` (any number, `0` included), `minlength`/`maxlength` and `pattern` add the corresponding constraint validators. As on a native input, `pattern` has to match the whole value, an expression that does not compile sets no rule, and `number`, `date`, `time` and `textarea` ignore it. The set is rebuilt whenever one of these props changes, also after load, as with the React wrappers under SSR: a pristine field only updates its required tip, a field already validated on blur is validated again. Custom validators can be attached at runtime through the `addValidator`/`removeValidator`/`hasValidator`/`getErrors` methods.\n- **Disabled / read-only tips**: `disabled` and `readonly` surface a persistent top tip describing the state; read-only fields also auto-select their text on focus.\n- **Character counter**: When `maxlength` is set a bottom counter tip shows `current / max` and shifts through fullness variants as the value approaches the limit. A `maxlength` of `0` or less is treated as unset.\n- **Password masking**: With `type=\"password\"` a toggle button reveals/hides the value; it is disabled with the field.\n- **Number steppers**: With `type=\"number\"` increment/decrement buttons are rendered; their placement follows `controlsLayout` and their glyphs follow `controlsIcon`. They are disabled on a disabled or read-only field, like the spin buttons of a native one.\n- **Speech-to-text**: When `mic` is set a dictation button transcribes speech into the value, replacing what was there, and emits `mdsInputSpeechEnd` when the user stops the dictation; when the Web Speech API is unavailable the button switches to an error state and the value is left as it is. The dictation button is disabled on a disabled or read-only field, which the user cannot change, and a dictation in progress stops, emitting `mdsInputSpeechEnd`, when the field becomes so.\n- **Emitted events**: `mdsInputChange` carries the new value, `mdsInputKeydown` fires on every key pressed in the field with the native `KeyboardEvent` as detail (before the value changes: read the value from `mdsInputChange`), and `mdsInputFocus`/`mdsInputBlur` fire on focus transitions.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` ladder (color role) is defined in [`agents/variants.md`](../../../../agents/variants.md); `<mds-input>` consumes it for both intent styling and validation feedback, but does not expose a `tone` prop. It accepts `primary` (default), `ai`, `info`, `success`, `warning` and `error`.\n\n- **`type`** selects both the rendered control and the validation profile: it covers the native HTML types plus format types (`'cf'`, `'piva'`, `'isbn'`, `'cc'`) and switches the host to a multi-line `<textarea>` for `'textarea'`.\n- **`variant=\"ai\"`** auto-assigns the AI chatbot icon when no `icon` is otherwise provided, signposting AI-assisted fields.\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner icon, stepper buttons and password and microphone toggles scale with it. A `textarea` keeps its own height (`--mds-input-textarea-min-height`).\n\n#### Other behavioral props\n\n- **`icon`** is an SVG filename slug from the Magma icon library shown at the leading (left) edge of the field; it is suppressed while `await` is active, since the spinner takes its place.\n- **`controlsLayout`** chooses between stacked (`'vertical'`) and split (`'horizontal'`) stepper buttons, and **`controlsIcon`** picks arrow vs. plus/minus glyphs - both apply only to `type=\"number\"`.\n- **`datalist`** supplies suggestion options for `type=\"search\"` style autocompletion.\n- **`tip`** renders inline helper text below the field, and **`typography`** selects the field's text scale.\n",
|
|
12354
|
+
"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 [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Text Input\n\nThe simplest form: set `name` for form participation and `placeholder` for a visual hint. Wrap the component in [`mds-input-field`](../mds-input-field/AGENTS.md) to add a visible label and associated tip.\n\n```html\n<mds-input\n name=\"cognome\"\n placeholder=\"Inserisci il tuo cognome\"\n></mds-input>\n```\n\n#### Required Field with `tip` Helper Text\n\nUse `required` to validate that the field is not empty and `tip` to explain the constraint. The component surfaces a top-tip when focused and drives `variant` to `'error'` or `'success'` on blur. When the field collects the user's own data, set the matching `autocomplete` token (`email`, `given-name`, `tel`, ...) so browsers can identify its purpose (WCAG 2.1 SC 1.3.5) and offer autofill; without it the component default `autocomplete=\"off\"` applies.\n\n```html\n<mds-input\n name=\"email\"\n type=\"email\"\n autocomplete=\"email\"\n placeholder=\"nome@esempio.it\"\n required\n tip=\"Inserisci un indirizzo email valido\"\n></mds-input>\n```\n\n#### Textarea for Multi-line Content\n\nSet `type=\"textarea\"` to render a `<textarea>` instead of a single-line `<input>`. Use the `--mds-input-textarea-*` custom properties to control height and resize behaviour.\n\n```html\n<mds-input\n name=\"descrizione\"\n type=\"textarea\"\n placeholder=\"Descrivi il problema...\"\n maxlength=\"500\"\n></mds-input>\n```\n\n#### Character Counter via `maxlength`\n\nWhen `maxlength` is set the component renders a live `current / max` counter below the field. The counter shifts through fullness variants as the limit approaches. A value of `0` or less is treated as unset.\n\n```html\n<mds-input\n name=\"titolo\"\n placeholder=\"Titolo dell'articolo\"\n maxlength=\"120\"\n></mds-input>\n```\n\n#### Numeric Input with Steppers\n\nSet `type=\"number\"` to enable built-in increment/decrement buttons. Use `controlsLayout` to choose between stacked (`'vertical'`, default) and split (`'horizontal'`) placement, and `controlsIcon` to pick arrow vs. plus/minus glyphs. Use `min`, `max`, and `step` to constrain the legal range.\n\n```html\n<!-- Stacked (default) - arrow glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"1\"\n max=\"99\"\n step=\"1\"\n placeholder=\"1\"\n></mds-input>\n\n<!-- Horizontal split - arithmetic glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"0\"\n max=\"100\"\n controls-layout=\"horizontal\"\n controls-icon=\"arithmetic\"\n placeholder=\"0\"\n></mds-input>\n```\n\n#### Password Input\n\nSet `type=\"password\"` to render a masked field with a built-in visibility toggle. The component renders a custom dot-mask overlay and a show/hide button - no extra wiring is needed. Always set `autocomplete` to `new-password` (sign-up, password change) or `current-password` (login): the component default is `autocomplete=\"off\"`, which browsers and password managers ignore on credential fields, but the explicit token is what lets them pair the password with its username field and fill or generate the right value.\n\n```html\n<mds-input\n name=\"password\"\n type=\"password\"\n autocomplete=\"new-password\"\n placeholder=\"Scegli una password\"\n required\n></mds-input>\n```\n\n#### Login Form\n\nPair a username field carrying `autocomplete=\"username\"` with a password field carrying `autocomplete=\"current-password\"` inside a `<form>`, and submit through `<mds-button type=\"submit\">`. The native fields live in the Shadow DOM of each `<mds-input>`: among the password managers tested, Bitwarden, LastPass, Chrome and Edge detect and fill them, Firefox's built-in manager and KeePassXC-Browser do not (they only look at the light DOM).\n\n```html\n<form action=\"/login\" method=\"post\">\n <mds-input-field label=\"Email\">\n <mds-input name=\"username\" type=\"email\" autocomplete=\"username\" required></mds-input>\n </mds-input-field>\n <mds-input-field label=\"Password\">\n <mds-input name=\"password\" type=\"password\" autocomplete=\"current-password\" required></mds-input>\n </mds-input-field>\n\n <mds-button type=\"submit\" label=\"Accedi\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Italian-Specific Masked Types\n\n`type=\"cf\"` installs the codice fiscale format and length validators and `type=\"isbn\"` a checksum validator. `type=\"piva\"` accepts 11 digits whose last one is the check digit, without the `IT` prefix or spaces, and `type=\"cc\"` 13 to 19 digits, in groups split by spaces or dashes, that pass the Luhn check of card numbers. A value that breaks the format stops the submit of the form. No type applies a keyboard mask.\n\n```html\n<mds-input name=\"codice_fiscale\" type=\"cf\" placeholder=\"RSSMRA80A01H501Z\"></mds-input>\n<mds-input name=\"partita_iva\" type=\"piva\" placeholder=\"01234567890\"></mds-input>\n```\n\n#### Search Input with Datalist\n\nUse `type=\"search\"` combined with the `datalist` prop to offer autocomplete suggestions from a fixed list. The list is rendered inside the shadow DOM and wired automatically.\n\n```html\n<mds-input\n name=\"comune\"\n type=\"search\"\n placeholder=\"Cerca comune...\"\n></mds-input>\n```\n\n```javascript\n// Pass suggestions as a JavaScript array\ndocument.querySelector('mds-input').datalist = ['Roma', 'Milano', 'Napoli', 'Torino'];\n```\n\n#### Icon Decoration\n\nThe `icon` prop renders an SVG slug from the Magma icon library at the leading edge of the field. The icon is suppressed while `await` is active and the spinner takes its place.\n\n```html\n<mds-input\n name=\"cerca\"\n type=\"search\"\n icon=\"mi/baseline/search\"\n placeholder=\"Cerca...\"\n></mds-input>\n```\n\n#### AI-Assisted Field\n\nSet `variant=\"ai\"` to signal an AI-powered field. When no `icon` prop is present, the component auto-assigns the AI chatbot icon.\n\n```html\n<mds-input\n name=\"prompt\"\n type=\"text\"\n variant=\"ai\"\n placeholder=\"Chiedi qualcosa all'assistente...\"\n></mds-input>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while an async operation (e.g. a lookup) is in flight. The component renders an inline spinner in place of the icon. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-input name=\"codice\" placeholder=\"Verifica in corso...\" await></mds-input>\n```\n\n#### Speech-to-Text Dictation\n\nSet the `mic` boolean attribute to render a dictation button. Starting a dictation clears the current value and writes the recognized speech in its place; the component emits `mdsInputSpeechEnd` when the user stops the dictation. If the Web Speech API is unavailable the button switches to an error state and the value is kept.\n\n```html\n<mds-input\n name=\"note_vocali\"\n type=\"text\"\n mic\n placeholder=\"Parla o scrivi...\"\n></mds-input>\n```\n\n#### Listening to Events\n\nListen for `mdsInputChange` instead of native `input` or `change`: `change` does not cross the shadow boundary, and `input` reports only typing, not the values set by the steppers, the dictation or a script.\n\n```javascript\ndocument.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {\n console.log(e.detail.value);\n});\n\ndocument.querySelector('mds-input').addEventListener('mdsInputValidation', (e) => {\n console.log('valido:', e.detail);\n});\n```\n\n#### Form Participation\n\n`<mds-input>` is form-associated. It submits natively inside a `<form>`; set `name` so the value is included in form data. Its validation is reported to the form too: an empty `required` field, or one that breaks another rule, stops the submit like a native input and shows the error. Add `novalidate` to the `<form>` when your own code validates on submit. A reset brings every field back to its value at load and to its pristine look.\n\n```html\n<form action=\"/salva\" method=\"post\">\n <mds-input name=\"nome\" type=\"text\" placeholder=\"Nome\" required></mds-input>\n <mds-input name=\"cognome\" type=\"text\" placeholder=\"Cognome\" required></mds-input>\n <mds-input name=\"email\" type=\"email\" placeholder=\"Email\" required></mds-input>\n\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n</form>\n```\n\n#### Read-Only Display\n\nUse `readonly` when the value should be visible but not editable. A persistent top tip describes the state, and the field text is auto-selected on focus for easy copying.\n\n```html\n<mds-input\n name=\"codice_riferimento\"\n value=\"REF-2024-00123\"\n readonly\n></mds-input>\n```\n\n#### Styling Customization\n\nStyle the input only through its documented `--mds-input-*` CSS custom properties. Set them on the host or a parent selector. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.search-bar mds-input {\n --mds-input-background: rgb(var(--magma-wash-base));\n --mds-input-placeholder-default-color: rgb(var(--magma-text-disabled));\n --mds-input-icon-color: rgb(var(--magma-accent-fg));\n}\n\n/* Textarea: fixed height, allow resize */\n.notes-area mds-input {\n --mds-input-textarea-min-height: 8rem;\n --mds-input-textarea-max-height: 24rem;\n --mds-input-textarea-resize: vertical;\n}\n```\n\n#### Sizing a Field to the Controls Next to It\n\nGive the fields of a row the `size` of the buttons beside them, so they share one height: `sm` 28px, `md` 36px, `lg` 48px (default), the sizes of [`<mds-button>`](../mds-button/AGENTS.md). `<mds-input-select>`, `<mds-input-date>` and `<mds-input-date-range>` take the same values.\n\n```html\n<div class=\"flex items-center gap-200\">\n <mds-input size=\"md\" type=\"search\" icon=\"mi/baseline/search\" placeholder=\"Cerca\"></mds-input>\n <mds-input-select size=\"md\" placeholder=\"Stato\">\n <option value=\"open\">Aperte</option>\n <option value=\"closed\">Chiuse</option>\n </mds-input-select>\n <mds-button size=\"md\" label=\"Filtra\"></mds-button>\n</div>\n```\n\n",
|
|
12355
12355
|
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Raw `<input>` When `<mds-input>` Exists\n\nReaching for a plain `<input>` bypasses theming, validation, tips, accessible state announcements, and form-reset behavior provided by the component.\n\n```html\n<!-- INCORRECT -->\n<input type=\"text\" name=\"nome\" placeholder=\"Nome\" class=\"my-input\">\n\n<!-- CORRECT -->\n<mds-input name=\"nome\" type=\"text\" placeholder=\"Nome\"></mds-input>\n```\n\n#### Do Not Set Boolean Attributes to the String `\"false\"`\n\n`disabled`, `required`, `readonly`, `mic` and `await` are boolean attributes: remove the attribute entirely to turn it off. The runtime happens to read the string `\"false\"` as `false`, but the attribute stays in the markup until the component renders, and HTML, the browser's own handling of `disabled` on a form-associated element, attribute selectors and `hasAttribute()` all read a present attribute as set.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"note\" disabled=\"false\" required=\"false\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input name=\"note\"></mds-input>\n```\n\n#### Do Not Force `variant` for Validation Feedback\n\nThe component drives `variant` to `'success'` or `'error'` automatically on blur when validators are active. Setting `variant` manually overrides the feedback and breaks the visual contract.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"codice\" variant=\"error\" tip=\"Valore non valido\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input name=\"codice\" required tip=\"Inserisci un valore valido\"></mds-input>\n```\n\n#### Do Not Listen to Native `input` or `change` Events\n\nThe native `change` event does not cross the shadow boundary, and `input` reports only typing, not the values set by the steppers, the dictation or a script. Use the documented `mdsInputChange` event instead, which fires for every value change.\n\n```javascript\n// INCORRECT\ndocument.querySelector('mds-input').addEventListener('input', (e) => {\n console.log(e.target.value);\n});\n\n// CORRECT\ndocument.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {\n console.log(e.detail.value);\n});\n```\n\n#### Do Not Use `type=\"number\"` Native Browser Spinners and Then Override the Input\n\nThe component renders its own increment/decrement buttons and hides the native browser spinners. Do not try to re-enable them via CSS, and do not add inline JS `stepUp`/`stepDown` calls - use the `controlsLayout` and `controlsIcon` props to configure the built-in controls.\n\n```html\n<!-- INCORRECT -->\n<mds-input type=\"number\" style=\"-moz-appearance: auto;\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input\n type=\"number\"\n controls-layout=\"horizontal\"\n controls-icon=\"arithmetic\"\n min=\"0\"\n max=\"100\"\n></mds-input>\n```\n\n#### Do Not Use a Legacy or Invalid `type` Value\n\n`<mds-input>` accepts a specific set of `type` values: `text`, `email`, `number`, `password`, `search`, `tel`, `url`, `date`, `time`, `textarea`, `cf`, `piva`, `cc`, `isbn`. Supplying anything else (e.g. `\"checkbox\"`, `\"radio\"`, `\"file\"`) is passed straight to the inner native `<input>`, which renders a bare native control that the component neither styles nor reports correctly to the form. Use the dedicated Magma component for those controls.\n\n```html\n<!-- INCORRECT -->\n<mds-input type=\"checkbox\" name=\"accetto\"></mds-input>\n<mds-input type=\"file\" name=\"allegato\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input-switch name=\"accetto\"></mds-input-switch>\n<mds-input-upload name=\"allegato\"></mds-input-upload>\n```\n\n#### Do Not Use `placeholder` as the Accessible Label\n\n`placeholder` disappears on input and is never read as a label by assistive tech. Always pair `<mds-input>` with [`mds-input-field`](../mds-input-field/AGENTS.md) (which shows a visible label and passes it down as the accessible name) or supply `aria-label` directly on the host.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"ricerca\" placeholder=\"Cerca per nome\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input-field label=\"Cerca per nome\">\n <mds-input name=\"ricerca\" placeholder=\"Cerca per nome\"></mds-input>\n</mds-input-field>\n```\n\n#### Do Not Pierce the Shadow DOM to Style Internal Parts\n\nThe supported customization surface is `--mds-input-*` CSS custom properties plus the documented shadow parts (`field`, `tip-top`, `tip-bottom`, `tip-count`, `password-toggle-button`, `counter-button-increase`, `counter-button-decrease`, `mic-toggle-button`). Targeting undocumented internals via `>>>` or arbitrary class names couples your code to the Shadow DOM implementation.\n\n```css\n/* INCORRECT */\nmds-input >>> .input {\n border: 2px solid red;\n}\n\n/* CORRECT */\nmds-input {\n --mds-input-ring: 0 0 0 2px rgb(var(--magma-danger-border));\n --mds-input-background: rgb(var(--magma-danger-wash-base));\n}\nmds-input::part(field) {\n font-style: italic;\n}\n```\n"
|
|
12356
12356
|
},
|
|
12357
12357
|
"props": [
|
|
@@ -13144,6 +13144,54 @@
|
|
|
13144
13144
|
"getter": false,
|
|
13145
13145
|
"setter": false
|
|
13146
13146
|
},
|
|
13147
|
+
{
|
|
13148
|
+
"name": "size",
|
|
13149
|
+
"type": "\"lg\" | \"md\" | \"sm\" | undefined",
|
|
13150
|
+
"complexType": {
|
|
13151
|
+
"original": "InputSizeType",
|
|
13152
|
+
"resolved": "\"lg\" | \"md\" | \"sm\" | undefined",
|
|
13153
|
+
"references": {
|
|
13154
|
+
"InputSizeType": {
|
|
13155
|
+
"location": "import",
|
|
13156
|
+
"path": "@type/input",
|
|
13157
|
+
"id": "src/type/input.ts::InputSizeType",
|
|
13158
|
+
"referenceLocation": "InputSizeType"
|
|
13159
|
+
}
|
|
13160
|
+
}
|
|
13161
|
+
},
|
|
13162
|
+
"mutable": false,
|
|
13163
|
+
"attr": "size",
|
|
13164
|
+
"reflectToAttr": true,
|
|
13165
|
+
"docs": "Specifies the height of the field, the same as `mds-button`: `sm` 28px, `md` 36px, `lg` 48px.\nA textarea keeps its own height (`--mds-input-textarea-min-height`)",
|
|
13166
|
+
"docsTags": [
|
|
13167
|
+
{
|
|
13168
|
+
"name": "default",
|
|
13169
|
+
"text": "'lg'"
|
|
13170
|
+
}
|
|
13171
|
+
],
|
|
13172
|
+
"default": "'lg'",
|
|
13173
|
+
"values": [
|
|
13174
|
+
{
|
|
13175
|
+
"value": "lg",
|
|
13176
|
+
"type": "string"
|
|
13177
|
+
},
|
|
13178
|
+
{
|
|
13179
|
+
"value": "md",
|
|
13180
|
+
"type": "string"
|
|
13181
|
+
},
|
|
13182
|
+
{
|
|
13183
|
+
"value": "sm",
|
|
13184
|
+
"type": "string"
|
|
13185
|
+
},
|
|
13186
|
+
{
|
|
13187
|
+
"type": "undefined"
|
|
13188
|
+
}
|
|
13189
|
+
],
|
|
13190
|
+
"optional": true,
|
|
13191
|
+
"required": false,
|
|
13192
|
+
"getter": false,
|
|
13193
|
+
"setter": false
|
|
13194
|
+
},
|
|
13147
13195
|
{
|
|
13148
13196
|
"name": "step",
|
|
13149
13197
|
"type": "string | undefined",
|
|
@@ -13915,7 +13963,7 @@
|
|
|
13915
13963
|
"docs": "",
|
|
13916
13964
|
"docsTags": [],
|
|
13917
13965
|
"usage": {
|
|
13918
|
-
"1. Description": "The `<mds-input-date>` web component is the Magma Design System control for capturing a single calendar date. It wraps a native `<input type=\"date\">`, adding form association, ISO value validation against an optional `min`/`max` range, contextual tips, and a button-triggered calendar dropdown for visual date picking.\n\n#### Semantic Behavior\n\n- **Form association**: The host participates natively in form submission and exposes its `value` under `name`; a form reset brings back the date the field had at load, both shown and submitted, and its pristine look, like a native input. An invalid value submits nothing, and its invalid state is reported to the form: like a native control, the field matches `:invalid` and stops the submit, with a message in the page language (a missing required date, a date out of the range, an unreadable one). A disabled or read-only field is left out, and `novalidate` on the `<form>` turns the check off.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **ISO value contract**: `value`, `min`, and `max` are all ISO date strings (`YYYY-MM-DD`); other formats are not accepted.\n- **Validation on change**: The value is checked when the component loads, on every value change and whenever `required`, `min` or `max` change (also after load, as with the React wrappers under SSR). The validity reported to the form, the submitted value and the required tip follow every check: a date invalid, missing while `required` or outside the `min`/`max` range submits no value. The look follows once the field is touched, like `:user-invalid` on a native control: after the user edits or leaves the field, picks a date from the calendar, or a stopped submit points at it, each check sets `variant` to `'error'` or `'primary'` and emits `mdsInputValidation` with a boolean. An empty `required` field therefore loads in its own variant, not in `'error'`.\n- **Range self-correction**: If `max` is earlier than `min`, at load or after a later change of either, `max` is snapped to equal `min`.\n- **Selection event**: `mdsInputDateSelect` fires with the new string value whenever `value` changes, whether typed or picked from the calendar.\n- **Calendar dropdown**: The trailing calendar button opens a single-date calendar; picking a day writes back the value and, after `delay`, auto-closes.\n- **Slotted mode**: When the host carries a `slot` attribute it is treated as embedded - the calendar button, dropdown, and calendar are not rendered, leaving only the bare input for composition inside a larger field.\n- **Contextual tips**: A tip surfaces `disabled`, `readonly`, and `required` states; the required tip expands on focus and reflects success once the value is valid.\n- **Read-only**: A read-only field shows its tip and auto-selects its text on focus; its native input is read-only and its calendar button disabled, so the value cannot be changed.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` ladder is defined in [`agents/variants.md`](../../../../agents/variants.md). Note that `variant` is mutable here: once the field is touched, the component overrides it to `'error'` / `'primary'` as validation dictates, so a variant set in the markup or from script lasts until the user edits or leaves the field.\n\n#### Other behavioral props\n\n- **`min`** / **`max`** bound the selectable range; dates outside it invalidate the field rather than being silently clamped.\n- **`delay`** is the milliseconds to wait before auto-closing the calendar dropdown after a pick; setting it to `0` keeps the dropdown open.\n- **`required`** makes an empty or invalid value fail validation and drives the required/required-success tip.\n",
|
|
13966
|
+
"1. Description": "The `<mds-input-date>` web component is the Magma Design System control for capturing a single calendar date. It wraps a native `<input type=\"date\">`, adding form association, ISO value validation against an optional `min`/`max` range, contextual tips, and a button-triggered calendar dropdown for visual date picking.\n\n#### Semantic Behavior\n\n- **Form association**: The host participates natively in form submission and exposes its `value` under `name`; a form reset brings back the date the field had at load, both shown and submitted, and its pristine look, like a native input. An invalid value submits nothing, and its invalid state is reported to the form: like a native control, the field matches `:invalid` and stops the submit, with a message in the page language (a missing required date, a date out of the range, an unreadable one). A disabled or read-only field is left out, and `novalidate` on the `<form>` turns the check off.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **ISO value contract**: `value`, `min`, and `max` are all ISO date strings (`YYYY-MM-DD`); other formats are not accepted.\n- **Validation on change**: The value is checked when the component loads, on every value change and whenever `required`, `min` or `max` change (also after load, as with the React wrappers under SSR). The validity reported to the form, the submitted value and the required tip follow every check: a date invalid, missing while `required` or outside the `min`/`max` range submits no value. The look follows once the field is touched, like `:user-invalid` on a native control: after the user edits or leaves the field, picks a date from the calendar, or a stopped submit points at it, each check sets `variant` to `'error'` or `'primary'` and emits `mdsInputValidation` with a boolean. An empty `required` field therefore loads in its own variant, not in `'error'`.\n- **Range self-correction**: If `max` is earlier than `min`, at load or after a later change of either, `max` is snapped to equal `min`.\n- **Selection event**: `mdsInputDateSelect` fires with the new string value whenever `value` changes, whether typed or picked from the calendar.\n- **Calendar dropdown**: The trailing calendar button, icon-only and named in the page language (the `lang` of `<html>`) (\"Open calendar\"), opens a single-date calendar; picking a day writes back the value and, after `delay`, auto-closes.\n- **Slotted mode**: When the host carries a `slot` attribute it is treated as embedded - the calendar button, dropdown, and calendar are not rendered, leaving only the bare input for composition inside a larger field.\n- **Contextual tips**: A tip surfaces `disabled`, `readonly`, and `required` states; the required tip expands on focus and reflects success once the value is valid.\n- **Read-only**: A read-only field shows its tip and auto-selects its text on focus; its native input is read-only and its calendar button disabled, so the value cannot be changed.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` ladder is defined in [`agents/variants.md`](../../../../agents/variants.md). Note that `variant` is mutable here: once the field is touched, the component overrides it to `'error'` / `'primary'` as validation dictates, so a variant set in the markup or from script lasts until the user edits or leaves the field.\n\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner calendar button scale with it.\n\n#### Other behavioral props\n\n- **`min`** / **`max`** bound the selectable range; dates outside it invalidate the field rather than being silently clamped.\n- **`delay`** is the milliseconds to wait before auto-closing the calendar dropdown after a pick; setting it to `0` keeps the dropdown open.\n- **`required`** makes an empty or invalid value fail validation and drives the required/required-success tip.\n",
|
|
13919
13967
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-input-date>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant ladder documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Date Input\n\nThe simplest form. Wrap in [`mds-input-field`](../mds-input-field/AGENTS.md) to attach a visible label. Use `name` so the value is submitted with the form.\n\n```html\n<mds-input-field label=\"Data di nascita\">\n <mds-input-date name=\"birthdate\"></mds-input-date>\n</mds-input-field>\n```\n\n#### Pre-filled Value\n\nSet `value` to an ISO date string (`YYYY-MM-DD`) to initialize the picker with a known date. Do not use other date formats.\n\n```html\n<mds-input-date name=\"dataScadenza\" value=\"2026-12-31\"></mds-input-date>\n```\n\n#### Required Field\n\nAdd `required` to make an empty or invalid date fail validation. The component surfaces a tip on focus; the field stops the submit while empty, and turns to `'error'` once the user leaves it empty or a stopped submit points at it, until a valid date is entered.\n\n```html\n<mds-input-field label=\"Data di inizio *\">\n <mds-input-date name=\"startDate\" required></mds-input-date>\n</mds-input-field>\n```\n\n#### Bounded Date Range\n\nUse `min` and `max` (both ISO strings) to restrict the selectable range. Dates outside the range invalidate the field and, once it is touched, emit `mdsInputValidation` with `false`. If `max` is earlier than `min` at load time, the component snaps `max` to equal `min`.\n\n```html\n<mds-input-date\n name=\"dataSopralluogo\"\n min=\"2026-01-01\"\n max=\"2026-12-31\"\n></mds-input-date>\n```\n\n#### Listening to Value Changes\n\nListen to `mdsInputDateSelect` (fires with the new ISO string) for every value change - whether typed or picked from the calendar. Listen to `mdsInputValidation` to react to validity changes.\n\n```html\n<mds-input-date id=\"picker\" name=\"dataEvento\"></mds-input-date>\n\n<script>\n const picker = document.getElementById('picker');\n\n picker.addEventListener('mdsInputDateSelect', (e) => {\n console.log('Data selezionata:', e.detail); // \"2026-06-15\"\n });\n\n picker.addEventListener('mdsInputValidation', (e) => {\n console.log('Valido:', e.detail); // true | false\n });\n</script>\n```\n\n#### Programmatic Value via `setValue`\n\nUse the `setValue` method to set the value from JavaScript; it emits `mdsInputDateSelect` and checks the value. Unlike a user interaction it does not touch the field: on a pristine field the validity reaches the form, but the variant and `mdsInputValidation` wait for the user.\n\n```html\n<mds-input-date id=\"datePicker\" name=\"dataConsegna\"></mds-input-date>\n\n<script>\n document.getElementById('datePicker').setValue('2026-09-01');\n</script>\n```\n\n#### Controlling Calendar Auto-close Delay\n\nThe calendar dropdown closes `delay` milliseconds after a date is picked (default 500 ms). Set `delay=\"0\"` to keep it open after selection - useful when the picker is used inside a form where the user might want to confirm before the overlay disappears.\n\n```html\n<!-- Default: closes 500 ms after pick -->\n<mds-input-date name=\"dataRiunione\" delay=\"500\"></mds-input-date>\n\n<!-- Keep open until the user dismisses manually -->\n<mds-input-date name=\"dataRiunione\" delay=\"0\"></mds-input-date>\n```\n\n#### Disabled and Read-only States\n\n`disabled` blocks all interaction and removes the field from the tab sequence. `readonly` keeps the field in the tab sequence and selects its text on focus, but the date cannot be changed: the native input is read-only and the calendar button disabled. Both surface a contextual tip.\n\n```html\n<!-- Disabled: no interaction at all -->\n<mds-input-date name=\"dataArchiviazione\" disabled value=\"2025-01-01\"></mds-input-date>\n\n<!-- Read-only: focusable, not editable -->\n<mds-input-date name=\"dataCreazione\" readonly value=\"2024-06-01\"></mds-input-date>\n```\n\n#### Form Participation\n\n`<mds-input-date>` is form-associated and submits its ISO value under `name`. A missing `required` date, or one out of the `min`/`max` range, stops the submit like a native control. A form reset brings back the date of load, both shown and submitted.\n\n```html\n<form action=\"/prenota\" method=\"post\">\n <mds-input-field label=\"Data prenotazione\">\n <mds-input-date name=\"bookingDate\" required></mds-input-date>\n </mds-input-field>\n <mds-button type=\"submit\" label=\"Conferma\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Slotted Mode Inside a Compound Field\n\nWhen the host carries a `slot` attribute, the component renders only the bare native input - the calendar button, dropdown, and calendar are suppressed. This is the correct way to embed the date input inside [`mds-input-date-range`](../mds-input-date-range/AGENTS.md) or a custom compound field.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\" name=\"rangeStart\"></mds-input-date>\n <mds-input-date slot=\"end\" name=\"rangeEnd\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Variant Override for External State Signalling\n\n`variant` is driven automatically by validation (`'error'` on invalid, `'primary'` on valid) once the field is touched. To communicate an external state, write it in the markup or set it from script: it lasts until the user edits or leaves the field. Values follow the theme input ladder: `primary` (default), `error`, `success`, `warning`, `info`, `ai`.\n\n```html\n<mds-input-date id=\"dataConferma\" name=\"dataConferma\" value=\"2026-03-15\"></mds-input-date>\n\n<script>\n // Pre-mark as success when the date was already validated server-side\n const field = document.getElementById('dataConferma');\n field.componentOnReady().then(() => {\n field.variant = 'success';\n });\n</script>\n```\n\n#### Styling Customization\n\nStyle the component only through its documented `--mds-input-date-*` CSS custom properties. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast work automatically.\n\n```css\n.booking-widget mds-input-date {\n --mds-input-date-background: rgb(var(--magma-wash-base));\n --mds-input-date-icon-color: rgb(var(--magma-accent-fg));\n --mds-input-date-ring: 0 0 0 2px rgb(var(--magma-border-focus) / 0.5);\n}\n```\n",
|
|
13920
13968
|
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Use Non-ISO Date Strings\n\n`value`, `min`, and `max` must be ISO 8601 date strings (`YYYY-MM-DD`). Any other format is passed to `DateTime.fromISO`, which marks the date invalid: a non-ISO `value` immediately trips validation, and a non-ISO `min` / `max` is silently ignored.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date value=\"31/12/2026\" max=\"31-12-2026\"></mds-input-date>\n\n<!-- CORRECT -->\n<mds-input-date value=\"2026-12-31\" max=\"2026-12-31\"></mds-input-date>\n```\n\n#### Do Not Hardcode `variant=\"error\"` to Signal Validation\n\nThe component manages `variant` automatically: it sets `'error'` when validation fails and restores `'primary'` when it passes. Hardcoding `variant=\"error\"` shows an error before the user has done anything, does not stop the submit, and is overwritten as soon as the user touches the field.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date name=\"dataScadenza\" variant=\"error\"></mds-input-date>\n\n<!-- CORRECT - let validation drive variant; listen to mdsInputValidation instead -->\n<mds-input-date name=\"dataScadenza\" required></mds-input-date>\n```\n\n#### Do Not Listen to the Native `change` or `input` Events\n\nThe component emits `mdsInputDateSelect` (value string) and `mdsInputValidation` (boolean). The native `change` event does not cross the shadow boundary, and `input` misses calendar-driven picks and values set from script.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date id=\"picker\" name=\"data\"></mds-input-date>\n<script>\n document.getElementById('picker').addEventListener('change', handler);\n</script>\n\n<!-- CORRECT -->\n<mds-input-date id=\"picker\" name=\"data\"></mds-input-date>\n<script>\n document.getElementById('picker').addEventListener('mdsInputDateSelect', handler);\n</script>\n```\n\n#### Do Not Use a Raw `<input type=\"date\">` as a Drop-in Replacement\n\nReplacing `<mds-input-date>` with a plain `<input type=\"date\">` loses form-association conventions, theming, the calendar overlay, the contextual tip, and all Magma accessibility defaults.\n\n```html\n<!-- INCORRECT -->\n<input type=\"date\" name=\"dataEvento\" />\n\n<!-- CORRECT -->\n<mds-input-date name=\"dataEvento\"></mds-input-date>\n```\n\n#### Do Not Set `disabled=\"false\"` or `readonly=\"false\"` to Remove the State\n\nBoolean attributes must be absent to be off. The runtime happens to read the string `\"false\"` as `false`, but the attribute stays in the markup until the component renders, and HTML, the browser's own handling of `disabled` on a form-associated element, attribute selectors and `hasAttribute()` all read a present attribute as set.\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(--magma-danger-border) / 0.8);\n}\nmds-input-date::part(input-date) {\n font-size: var(--text-size-info-caption);\n}\n```\n\n#### Do Not Set `value` to Clear the Field\n\nSetting `value=\"\"` is the correct way to clear; do not set `value` to a non-ISO string expecting the component to silently ignore it - it passes through validation and trips an error state.\n\n```html\n<!-- INCORRECT (non-ISO value to \"reset\") -->\n<mds-input-date name=\"data\" value=\"clear\"></mds-input-date>\n\n<!-- CORRECT -->\n<mds-input-date name=\"data\" value=\"\"></mds-input-date>\n```\n"
|
|
13921
13969
|
},
|
|
@@ -14202,6 +14250,54 @@
|
|
|
14202
14250
|
"getter": false,
|
|
14203
14251
|
"setter": false
|
|
14204
14252
|
},
|
|
14253
|
+
{
|
|
14254
|
+
"name": "size",
|
|
14255
|
+
"type": "\"lg\" | \"md\" | \"sm\" | undefined",
|
|
14256
|
+
"complexType": {
|
|
14257
|
+
"original": "InputSizeType",
|
|
14258
|
+
"resolved": "\"lg\" | \"md\" | \"sm\" | undefined",
|
|
14259
|
+
"references": {
|
|
14260
|
+
"InputSizeType": {
|
|
14261
|
+
"location": "import",
|
|
14262
|
+
"path": "@type/input",
|
|
14263
|
+
"id": "src/type/input.ts::InputSizeType",
|
|
14264
|
+
"referenceLocation": "InputSizeType"
|
|
14265
|
+
}
|
|
14266
|
+
}
|
|
14267
|
+
},
|
|
14268
|
+
"mutable": false,
|
|
14269
|
+
"attr": "size",
|
|
14270
|
+
"reflectToAttr": true,
|
|
14271
|
+
"docs": "Specifies the height of the field, the same as `mds-button`: `sm` 28px, `md` 36px, `lg` 48px",
|
|
14272
|
+
"docsTags": [
|
|
14273
|
+
{
|
|
14274
|
+
"name": "default",
|
|
14275
|
+
"text": "'lg'"
|
|
14276
|
+
}
|
|
14277
|
+
],
|
|
14278
|
+
"default": "'lg'",
|
|
14279
|
+
"values": [
|
|
14280
|
+
{
|
|
14281
|
+
"value": "lg",
|
|
14282
|
+
"type": "string"
|
|
14283
|
+
},
|
|
14284
|
+
{
|
|
14285
|
+
"value": "md",
|
|
14286
|
+
"type": "string"
|
|
14287
|
+
},
|
|
14288
|
+
{
|
|
14289
|
+
"value": "sm",
|
|
14290
|
+
"type": "string"
|
|
14291
|
+
},
|
|
14292
|
+
{
|
|
14293
|
+
"type": "undefined"
|
|
14294
|
+
}
|
|
14295
|
+
],
|
|
14296
|
+
"optional": true,
|
|
14297
|
+
"required": false,
|
|
14298
|
+
"getter": false,
|
|
14299
|
+
"setter": false
|
|
14300
|
+
},
|
|
14205
14301
|
{
|
|
14206
14302
|
"name": "value",
|
|
14207
14303
|
"type": "string",
|
|
@@ -14557,7 +14653,7 @@
|
|
|
14557
14653
|
}
|
|
14558
14654
|
],
|
|
14559
14655
|
"usage": {
|
|
14560
|
-
"1. Description": "The `<mds-input-date-range>` web component is the Magma Design System control for capturing a start/end date pair, composing two slotted `<mds-input-date>` fields with a shared pop-up `mds-calendar` (in range mode) and optional quick-pick presets. It is a form-associated compound parent that orchestrates its children rather than rendering its own native inputs.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects exactly two `<mds-input-date>` children assigned to the `start` and `end` named slots; the host keeps both in sync as a single range - it is not meant to be used with a default (text) slot.\n- **Form association**: The submitted value is a JSON string `{ startDate, endDate }`; an empty range submits no value. On form reset it restores the start/end dates present at first load.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables its calendar button as `disabled` does, while the slotted fields, being inside the fieldset too, follow it themselves: the range cannot be changed and is left out of the form, until the fieldset is enabled.\n- **Range coercion**: When both dates are valid and the end falls before the start, the end is snapped to equal the start, also for a preselection that ends before it starts, so the committed range is never inverted.\n- **Min/max guard**: If `max` is earlier than `min` at load, `max` is clamped up to `min`; both bounds are forwarded to the calendar to block out-of-range selection, and to the slotted fields, which flag a date typed outside them and stop the submit; such a range is not emitted.\n- **Commit on blur**: Leaving the component validates the range, syncs the form value, and - when both dates are valid - emits selection.\n- **Calendar selection**: Picking a complete range in the pop-up calendar emits selection and, unless `delay` is `0`, auto-closes the dropdown after the delay.\n- **Preselection sync**: Slotted `mds-input-date-range-preselection` children act as quick-picks; activating one applies its range, and any external/calendar change re-evaluates which preset (if any) is marked selected; a preset matching the dates of load is marked selected from the start.\n- **Emitted events**: `mdsInputDateRangeValueChange` fires when a full, valid range is committed (calendar pick, preset, or focus-out with two valid dates) and either bound actually changed since the last emit.\n- **Focus management**: Clicking the host or either field label focuses the corresponding date input; a built-in calendar icon button toggles the calendar dropdown.\n- **Localization**: The \"from\"/\"to\" field labels and the calendar honor the resolved language (el/en/es/it).\n\n#### Properties & Visual Configurations\n\n- **`startDate` / `endDate`** are the controlled range bounds in ISO `YYYY-MM-DD` form; changing them externally re-syncs the slotted inputs and the calendar.\n- **`min` / `max`** define the selectable window: the calendar blocks the dates outside it, and the host passes both bounds to the slotted fields, which check a typed date against them. A bound the range does not set leaves the one written on a field alone; one changed after load reaches both fields.\n- **`disabled`** disables the range, like a disabled native input: the calendar button is disabled, a calendar left open closes, and the dates are left out of the form. It disables the two slotted fields too: at load only when it is set, so a field disabled on its own stays disabled; a change after load reaches both fields.\n- **`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",
|
|
14656
|
+
"1. Description": "The `<mds-input-date-range>` web component is the Magma Design System control for capturing a start/end date pair, composing two slotted `<mds-input-date>` fields with a shared pop-up `mds-calendar` (in range mode) and optional quick-pick presets. It is a form-associated compound parent that orchestrates its children rather than rendering its own native inputs.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects exactly two `<mds-input-date>` children assigned to the `start` and `end` named slots; the host keeps both in sync as a single range - it is not meant to be used with a default (text) slot.\n- **Form association**: The submitted value is a JSON string `{ startDate, endDate }`; an empty range submits no value. On form reset it restores the start/end dates present at first load.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables its calendar button as `disabled` does, while the slotted fields, being inside the fieldset too, follow it themselves: the range cannot be changed and is left out of the form, until the fieldset is enabled.\n- **Range coercion**: When both dates are valid and the end falls before the start, the end is snapped to equal the start, also for a preselection that ends before it starts, so the committed range is never inverted.\n- **Min/max guard**: If `max` is earlier than `min` at load, `max` is clamped up to `min`; both bounds are forwarded to the calendar to block out-of-range selection, and to the slotted fields, which flag a date typed outside them and stop the submit; such a range is not emitted.\n- **Commit on blur**: Leaving the component validates the range, syncs the form value, and - when both dates are valid - emits selection.\n- **Calendar selection**: Picking a complete range in the pop-up calendar emits selection and, unless `delay` is `0`, auto-closes the dropdown after the delay.\n- **Preselection sync**: Slotted `mds-input-date-range-preselection` children act as quick-picks; activating one applies its range, and any external/calendar change re-evaluates which preset (if any) is marked selected; a preset matching the dates of load is marked selected from the start.\n- **Emitted events**: `mdsInputDateRangeValueChange` fires when a full, valid range is committed (calendar pick, preset, or focus-out with two valid dates) and either bound actually changed since the last emit.\n- **Focus management**: Clicking the host or either field label focuses the corresponding date input; a built-in calendar icon button, named in the page language (the `lang` of `<html>`) (\"Open calendar\"), toggles the calendar dropdown.\n- **Localization**: The \"from\"/\"to\" field labels and the calendar honor the resolved language (el/en/es/it).\n\n#### Properties & Visual Configurations\n\n- **`startDate` / `endDate`** are the controlled range bounds in ISO `YYYY-MM-DD` form; changing them externally re-syncs the slotted inputs and the calendar.\n- **`min` / `max`** define the selectable window: the calendar blocks the dates outside it, and the host passes both bounds to the slotted fields, which check a typed date against them. A bound the range does not set leaves the one written on a field alone; one changed after load reaches both fields.\n- **`disabled`** disables the range, like a disabled native input: the calendar button is disabled, a calendar left open closes, and the dates are left out of the form. It disables the two slotted fields too: at load only when it is set, so a field disabled on its own stays disabled; a change after load reaches both fields.\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner calendar button scale with it.\n- **`delay`** is the auto-close grace period (ms) after a complete selection; set it to `0` to keep the calendar open until the user dismisses it manually.\n",
|
|
14561
14657
|
"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 shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Minimal Range Picker\n\nThe canonical form. Slot one [`mds-input-date`](../mds-input-date/AGENTS.md) as `start` and another as `end`; the host wires them together, drives the shared calendar, and handles range validation automatically.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Pre-filling the Range\n\nUse the `start-date` and `end-date` attributes to set an initial selection. Both expect ISO `YYYY-MM-DD` strings. Changing them later re-syncs the slotted inputs and the calendar automatically.\n\n```html\n<mds-input-date-range start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Constraining the Selectable Window\n\nUse `min` and `max` to block out-of-window dates in the calendar. Both are ISO `YYYY-MM-DD` strings. The host passes them to the slotted fields too: a date typed out of the window turns its field to error, stops the submit of the form and is not emitted as a range.\n\n```html\n<mds-input-date-range min=\"2026-01-01\" max=\"2026-12-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Listening to Range Events\n\n`mdsInputDateRangeValueChange` fires when a full, valid range is committed (calendar pick, preset, or focus-out with two valid dates) and either bound actually changed since the last emit. It delivers `{ startDate, endDate }` in `event.detail`.\n\n```html\n<mds-input-date-range id=\"periodo\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<script>\n document.querySelector('#periodo').addEventListener('mdsInputDateRangeValueChange', (e) => {\n console.log('Intervallo selezionato:', e.detail.startDate, '-', e.detail.endDate);\n });\n</script>\n```\n\n#### Form Participation\n\n`<mds-input-date-range>` is form-associated. Add `name` and place it inside a `<form>`; the submitted value is a JSON string `{ startDate, endDate }`. An empty range submits no value. Form reset restores the dates set at first load.\n\n```html\n<form action=\"/filtra\" method=\"get\">\n <mds-input-date-range name=\"periodo\" start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n </mds-input-date-range>\n <mds-button type=\"submit\" label=\"Applica filtro\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Reimposta\" variant=\"dark\" tone=\"outline\"></mds-button>\n</form>\n```\n\n#### Quick-Pick Preselections\n\nSlot one or more [`mds-input-date-range-preselection`](../mds-input-date-range-preselection/AGENTS.md) elements into the component. They appear inside the calendar dropdown and act as one-click range shortcuts. The host marks the matching preset as selected, from load on and whenever the range changes to match it. A preset whose end comes before its start applies its start as both ends.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n <mds-input-date-range-preselection start=\"2026-06-02\" end=\"2026-06-08\">\n Questa settimana\n </mds-input-date-range-preselection>\n <mds-input-date-range-preselection start=\"2026-06-01\" end=\"2026-06-30\">\n Questo mese\n </mds-input-date-range-preselection>\n</mds-input-date-range>\n```\n\n#### Controlling the Auto-Close Delay\n\nBy default the calendar closes 500 ms after a complete range is picked. Set `delay=\"0\"` to keep it open until the user dismisses it manually, or increase the value for a longer grace period.\n\n```html\n<!-- Keep the calendar open after selection -->\n<mds-input-date-range delay=\"0\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<!-- Longer grace period: 1 second -->\n<mds-input-date-range delay=\"1000\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Styling Customization\n\nStyle the component only through its documented `--mds-input-date-range-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` ([`agents/color.md`](../../../../agents/color.md)) so dark mode and themes keep working.\n\n```css\n.filtro-avanzato mds-input-date-range {\n --mds-input-date-range-background: rgb(var(--magma-surface-sunken));\n --mds-input-date-range-icon-color: rgb(var(--magma-accent-fg));\n --mds-input-date-range-fields-gap: 0 calc(var(--spacing) * 400);\n}\n```\n",
|
|
14562
14658
|
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Omit the Named Slots\n\nThe host renders two named slots (`start` and `end`) and wires them together internally. Without slotted `<mds-input-date>` children the component has no visible inputs and no data to commit.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Slot Raw `<input>` Elements\n\nThe `start` and `end` slots expect [`mds-input-date`](../mds-input-date/AGENTS.md) children. The host calls `.setValue()` and `.focusInput()` on the assigned element; a native `<input>` does not expose those methods and will break internal orchestration.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range>\n <input type=\"date\" slot=\"start\" />\n <input type=\"date\" slot=\"end\" />\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Disable the Fields Instead of the Range\n\nDisabling the slotted fields leaves the calendar button of the range enabled, and the user can still change the dates from the calendar. Set `disabled` on the range: it disables its calendar button and the two fields, and leaves the dates out of the form.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range name=\"period\">\n <mds-input-date slot=\"start\" disabled></mds-input-date>\n <mds-input-date slot=\"end\" disabled></mds-input-date>\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range name=\"period\" disabled>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Use Non-ISO Date Strings\n\n`startDate`, `endDate`, `min`, and `max` all require `YYYY-MM-DD` ISO format. Passing a locale-formatted string (e.g. `\"01/06/2026\"`) is silently invalid for Luxon's `DateTime.fromISO()` and leaves the range empty or unguarded.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range start-date=\"01/06/2026\" end-date=\"30/06/2026\" min=\"01/01/2026\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range start-date=\"2026-06-01\" end-date=\"2026-06-30\" min=\"2026-01-01\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Listen to Native `change` or `input` Events\n\nThe component emits `mdsInputDateRangeValueChange` as a documented custom event. Native `change` / `input` events originate from inside the shadow DOM and do not bubble out reliably.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range id=\"range\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n<script>\n document.querySelector('#range').addEventListener('change', handler);\n</script>\n\n<!-- CORRECT -->\n<mds-input-date-range id=\"range\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n<script>\n document.querySelector('#range').addEventListener('mdsInputDateRangeValueChange', handler);\n</script>\n```\n\n#### Do Not Set `delay=\"false\"` to Disable Auto-Close\n\n`delay` is a numeric prop, not a boolean. The string `\"false\"` is parsed as `NaN`, which is not `0`: the dropdown then closes at once instead of staying open. Use `delay=\"0\"` to keep the calendar open after selection.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range delay=\"false\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range delay=\"0\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Slot Preselection Elements Without the Component's Calendar\n\n[`mds-input-date-range-preselection`](../mds-input-date-range-preselection/AGENTS.md) children must be direct children of `<mds-input-date-range>`. Outside the component a click finds no range to apply (the preset looks for its closest `mds-input-date-range`); inside a wrapper div the preset is not slotted into the calendar dropdown and never shows.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n<mds-input-date-range-preselection start=\"2026-06-01\" end=\"2026-06-30\">\n Questo mese\n</mds-input-date-range-preselection>\n\n<!-- CORRECT -->\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n <mds-input-date-range-preselection start=\"2026-06-01\" end=\"2026-06-30\">\n Questo mese\n </mds-input-date-range-preselection>\n</mds-input-date-range>\n```\n\n#### Do Not Omit `name` When Inside a Form\n\nWithout `name` the component is form-associated but submits no named field, so the date range is invisible to the server and to `FormData`.\n\n```html\n<!-- INCORRECT -->\n<form action=\"/filtra\" method=\"get\">\n <mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n </mds-input-date-range>\n</form>\n\n<!-- CORRECT -->\n<form action=\"/filtra\" method=\"get\">\n <mds-input-date-range name=\"periodo\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n </mds-input-date-range>\n</form>\n```\n"
|
|
14563
14659
|
},
|
|
@@ -14842,6 +14938,54 @@
|
|
|
14842
14938
|
"getter": false,
|
|
14843
14939
|
"setter": false
|
|
14844
14940
|
},
|
|
14941
|
+
{
|
|
14942
|
+
"name": "size",
|
|
14943
|
+
"type": "\"lg\" | \"md\" | \"sm\" | undefined",
|
|
14944
|
+
"complexType": {
|
|
14945
|
+
"original": "InputSizeType",
|
|
14946
|
+
"resolved": "\"lg\" | \"md\" | \"sm\" | undefined",
|
|
14947
|
+
"references": {
|
|
14948
|
+
"InputSizeType": {
|
|
14949
|
+
"location": "import",
|
|
14950
|
+
"path": "@type/input",
|
|
14951
|
+
"id": "src/type/input.ts::InputSizeType",
|
|
14952
|
+
"referenceLocation": "InputSizeType"
|
|
14953
|
+
}
|
|
14954
|
+
}
|
|
14955
|
+
},
|
|
14956
|
+
"mutable": false,
|
|
14957
|
+
"attr": "size",
|
|
14958
|
+
"reflectToAttr": true,
|
|
14959
|
+
"docs": "Specifies the height of the field, the same as `mds-button`: `sm` 28px, `md` 36px, `lg` 48px",
|
|
14960
|
+
"docsTags": [
|
|
14961
|
+
{
|
|
14962
|
+
"name": "default",
|
|
14963
|
+
"text": "'lg'"
|
|
14964
|
+
}
|
|
14965
|
+
],
|
|
14966
|
+
"default": "'lg'",
|
|
14967
|
+
"values": [
|
|
14968
|
+
{
|
|
14969
|
+
"value": "lg",
|
|
14970
|
+
"type": "string"
|
|
14971
|
+
},
|
|
14972
|
+
{
|
|
14973
|
+
"value": "md",
|
|
14974
|
+
"type": "string"
|
|
14975
|
+
},
|
|
14976
|
+
{
|
|
14977
|
+
"value": "sm",
|
|
14978
|
+
"type": "string"
|
|
14979
|
+
},
|
|
14980
|
+
{
|
|
14981
|
+
"type": "undefined"
|
|
14982
|
+
}
|
|
14983
|
+
],
|
|
14984
|
+
"optional": true,
|
|
14985
|
+
"required": false,
|
|
14986
|
+
"getter": false,
|
|
14987
|
+
"setter": false
|
|
14988
|
+
},
|
|
14845
14989
|
{
|
|
14846
14990
|
"name": "startDate",
|
|
14847
14991
|
"type": "string",
|
|
@@ -15886,8 +16030,8 @@
|
|
|
15886
16030
|
}
|
|
15887
16031
|
],
|
|
15888
16032
|
"usage": {
|
|
15889
|
-
"1. Description": "The `<mds-input-select>` web component is the Magma Design System single- and multi-choice dropdown control. It wraps a native `<select>` element, adding form association, accessible status feedback, and themed chrome while accepting plain `<option>` elements through its default slot.\n\n#### Semantic Behavior\n\n- **Native select wrapping**: It renders a real `<select>` (exposed as the `select` part) so keyboard, type-ahead, and platform option lists work natively; the host owns theming and status only.\n- **Slotted options**: The default slot accepts `<option>` (and `<optgroup>`) markup; the current selection re-syncs whenever the slotted content changes.\n- **Form association**: The selection is pushed to the host form: a single select submits its `value`, a `multiple` one an entry per selected option under `name`, as a native select. A form reset brings back the selection of load, like a native select: the options the markup marks `selected` (or the placeholder), with the `value` of load on top. Toggling `disabled` removes the value from the submitted form data.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **Form validity**: A `required` select left empty is reported to the form as a native one: it matches `:invalid` and stops the submit, with a message in the page language. A disabled select is left out, and `novalidate` on the `<form>` turns the check off.\n- **Value syncing**: Changing the selection (by user input, the `setValue()` method, or the prop) emits `mdsInputSelectChange` with `{ value, values }` in `detail`: `value` is the first selected option as a string, `values` the values of every selected option, the placeholder left out. A `value` set by code selects its `<option>` alone, as `select.value` does, and a value cleared by code goes back to the placeholder.\n- **Placeholder option**: When `placeholder` is set, a leading empty-value `<option>` is injected as the first entry; if `required` is set that placeholder is disabled so it cannot be re-selected after a valid choice.\n- **Default selection fallback**: With no explicit value, the options the markup marks `selected` become the selection; without them, the placeholder or, with no placeholder, the first option of a single select. A `defaultValue` seeds `value` at load.\n- **Status tip**: A status tip surfaces verbose state - a disabled notice, and for required fields a `required` / `required-success` message that expands while the control has focus.\n\n#### Properties & Visual Configurations\n\nThe `variant` prop applies a status appearance drawn from the shared status ladder in [`agents/variants.md`](../../../../agents/variants.md) - use it to reflect validation outcome (`'error'`, `'success'`, `'warning'`, `'info'`) rather than decorative styling. This component exposes no separate `tone` prop.\n\n#### Other behavioral props\n\n- **`multiple`** turns the control into a multi-select list box: the form gets an entry per selected option and `values` in the `mdsInputSelectChange` detail lists them all, while `value` holds the first one, as `select.value` does. **`
|
|
15890
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-input-select>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Select with Placeholder\n\nThe canonical form. Slot plain `<option>` elements as direct children. Set `placeholder` to inject a leading empty-value entry that prompts the user before a choice is made.\n\n```html\n<mds-input-select name=\"categoria\" placeholder=\"Seleziona una categoria...\">\n <option value=\"news\">Notizie</option>\n <option value=\"eventi\">Eventi</option>\n <option value=\"avvisi\">Avvisi</option>\n</mds-input-select>\n```\n\n#### Required Select Inside a Form\n\nAdding `required` enforces a non-empty submission - an empty select stops the submit like a native one - and disables the placeholder option once a valid choice exists, so users cannot revert to the empty entry. Place the component inside a `<form>` - it is form-associated and submits natively.\n\n```html\n<form action=\"/salva\" method=\"post\">\n <mds-input-select name=\"regione\" required placeholder=\"Scegli la regione...\">\n <option value=\"lombardia\">Lombardia</option>\n <option value=\"veneto\">Veneto</option>\n <option value=\"toscana\">Toscana</option>\n </mds-input-select>\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Pre-selected Value via `value`\n\nPass `value` to open the component with a specific option already chosen. The matching `<option>` is marked selected automatically. Use `default-value` instead when the initial selection is set once at load and you do not need live two-way binding (notably in the React wrapper).\n\n```html\n<!-- Live controlled value -->\n<mds-input-select name=\"priorita\" value=\"alta\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n\n<!-- Initial seed value for React / SSR -->\n<mds-input-select name=\"priorita\" default-value=\"media\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n```\n\n#### Listening to Value Changes\n\nListen to `mdsInputSelectChange` - do not rely on the native `change` event, which may not bubble out of shadow DOM reliably. The event detail carries the chosen value as a string in `value`, and the values of every selected option in `values`.\n\n```html\n<mds-input-select id=\"stato-pratica\" name=\"stato\" placeholder=\"Seleziona stato...\">\n <option value=\"bozza\">Bozza</option>\n <option value=\"in-lavorazione\">In lavorazione</option>\n <option value=\"chiusa\">Chiusa</option>\n</mds-input-select>\n\n<script>\n document.getElementById('stato-pratica')\n .addEventListener('mdsInputSelectChange', (event) => {\n console.log('Nuovo stato:', event.detail.value);\n });\n</script>\n```\n\n#### Programmatic Value via `setValue()`\n\nUse the `setValue()` async method when you need to change the selection from JavaScript after the component has rendered - for example when a related control resets the form state.\n\n```html\n<mds-input-select id=\"provincia\" name=\"provincia\" placeholder=\"Seleziona provincia...\">\n <option value=\"MI\">Milano</option>\n <option value=\"RM\">Roma</option>\n <option value=\"TO\">Torino</option>\n</mds-input-select>\n\n<script>\n async function resetSelezione() {\n const el = document.getElementById('provincia');\n await el.setValue('MI');\n }\n</script>\n```\n\n#### Disabled State\n\nSet `disabled` as a boolean attribute to block interaction and remove the value from the submitted form data. A status tip is shown automatically while the component is disabled.\n\n```html\n<mds-input-select name=\"tipo-contratto\" disabled placeholder=\"Non disponibile\">\n <option value=\"td\">Tempo determinato</option>\n <option value=\"ti\">Tempo indeterminato</option>\n</mds-input-select>\n```\n\n#### Multi-select List Box\n\n`multiple` switches the component to a scrollable list that allows zero or more simultaneous selections. Use `
|
|
16033
|
+
"1. Description": "The `<mds-input-select>` web component is the Magma Design System single- and multi-choice dropdown control. It wraps a native `<select>` element, adding form association, accessible status feedback, and themed chrome while accepting plain `<option>` elements through its default slot.\n\n#### Semantic Behavior\n\n- **Native select wrapping**: It renders a real `<select>` (exposed as the `select` part) so keyboard, type-ahead, and platform option lists work natively; the host owns theming and status only.\n- **Slotted options**: The default slot accepts `<option>` (and `<optgroup>`) markup; the current selection re-syncs whenever the slotted content changes.\n- **Form association**: The selection is pushed to the host form: a single select submits its `value`, a `multiple` one an entry per selected option under `name`, as a native select. A form reset brings back the selection of load, like a native select: the options the markup marks `selected` (or the placeholder), with the `value` of load on top. Toggling `disabled` removes the value from the submitted form data.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **Form validity**: A `required` select left empty is reported to the form as a native one: it matches `:invalid` and stops the submit, with a message in the page language. A disabled select is left out, and `novalidate` on the `<form>` turns the check off.\n- **Value syncing**: Changing the selection (by user input, the `setValue()` method, or the prop) emits `mdsInputSelectChange` with `{ value, values }` in `detail`: `value` is the first selected option as a string, `values` the values of every selected option, the placeholder left out. A `value` set by code selects its `<option>` alone, as `select.value` does, and a value cleared by code goes back to the placeholder.\n- **Placeholder option**: When `placeholder` is set, a leading empty-value `<option>` is injected as the first entry; if `required` is set that placeholder is disabled so it cannot be re-selected after a valid choice.\n- **Default selection fallback**: With no explicit value, the options the markup marks `selected` become the selection; without them, the placeholder or, with no placeholder, the first option of a single select. A `defaultValue` seeds `value` at load.\n- **Status tip**: A status tip surfaces verbose state - a disabled notice, and for required fields a `required` / `required-success` message that expands while the control has focus.\n\n#### Properties & Visual Configurations\n\nThe `variant` prop applies a status appearance drawn from the shared status ladder in [`agents/variants.md`](../../../../agents/variants.md) - use it to reflect validation outcome (`'error'`, `'success'`, `'warning'`, `'info'`) rather than decorative styling. This component exposes no separate `tone` prop.\n\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner arrow scale with it.\n\n#### Other behavioral props\n\n- **`multiple`** turns the control into a multi-select list box: the form gets an entry per selected option and `values` in the `mdsInputSelectChange` detail lists them all, while `value` holds the first one, as `select.value` does. **`rows`** sets how many option rows are visible at once, as the `size` of a native `<select>`: above `1` it shows a list box even without `multiple`. A number in `size`, the row count it used to set, still works as `rows` but warns: it is deprecated and goes in the next major.\n- **`defaultValue`** is the initial selection used to seed the value at load (notably for the React wrapper), distinct from the live `value` that reflects the current choice.\n- **`required`** both enforces a non-empty submission and locks the placeholder option so the empty entry cannot be chosen again.\n",
|
|
16034
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-input-select>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Select with Placeholder\n\nThe canonical form. Slot plain `<option>` elements as direct children. Set `placeholder` to inject a leading empty-value entry that prompts the user before a choice is made.\n\n```html\n<mds-input-select name=\"categoria\" placeholder=\"Seleziona una categoria...\">\n <option value=\"news\">Notizie</option>\n <option value=\"eventi\">Eventi</option>\n <option value=\"avvisi\">Avvisi</option>\n</mds-input-select>\n```\n\n#### Required Select Inside a Form\n\nAdding `required` enforces a non-empty submission - an empty select stops the submit like a native one - and disables the placeholder option once a valid choice exists, so users cannot revert to the empty entry. Place the component inside a `<form>` - it is form-associated and submits natively.\n\n```html\n<form action=\"/salva\" method=\"post\">\n <mds-input-select name=\"regione\" required placeholder=\"Scegli la regione...\">\n <option value=\"lombardia\">Lombardia</option>\n <option value=\"veneto\">Veneto</option>\n <option value=\"toscana\">Toscana</option>\n </mds-input-select>\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Pre-selected Value via `value`\n\nPass `value` to open the component with a specific option already chosen. The matching `<option>` is marked selected automatically. Use `default-value` instead when the initial selection is set once at load and you do not need live two-way binding (notably in the React wrapper).\n\n```html\n<!-- Live controlled value -->\n<mds-input-select name=\"priorita\" value=\"alta\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n\n<!-- Initial seed value for React / SSR -->\n<mds-input-select name=\"priorita\" default-value=\"media\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n```\n\n#### Listening to Value Changes\n\nListen to `mdsInputSelectChange` - do not rely on the native `change` event, which may not bubble out of shadow DOM reliably. The event detail carries the chosen value as a string in `value`, and the values of every selected option in `values`.\n\n```html\n<mds-input-select id=\"stato-pratica\" name=\"stato\" placeholder=\"Seleziona stato...\">\n <option value=\"bozza\">Bozza</option>\n <option value=\"in-lavorazione\">In lavorazione</option>\n <option value=\"chiusa\">Chiusa</option>\n</mds-input-select>\n\n<script>\n document.getElementById('stato-pratica')\n .addEventListener('mdsInputSelectChange', (event) => {\n console.log('Nuovo stato:', event.detail.value);\n });\n</script>\n```\n\n#### Programmatic Value via `setValue()`\n\nUse the `setValue()` async method when you need to change the selection from JavaScript after the component has rendered - for example when a related control resets the form state.\n\n```html\n<mds-input-select id=\"provincia\" name=\"provincia\" placeholder=\"Seleziona provincia...\">\n <option value=\"MI\">Milano</option>\n <option value=\"RM\">Roma</option>\n <option value=\"TO\">Torino</option>\n</mds-input-select>\n\n<script>\n async function resetSelezione() {\n const el = document.getElementById('provincia');\n await el.setValue('MI');\n }\n</script>\n```\n\n#### Disabled State\n\nSet `disabled` as a boolean attribute to block interaction and remove the value from the submitted form data. A status tip is shown automatically while the component is disabled.\n\n```html\n<mds-input-select name=\"tipo-contratto\" disabled placeholder=\"Non disponibile\">\n <option value=\"td\">Tempo determinato</option>\n <option value=\"ti\">Tempo indeterminato</option>\n</mds-input-select>\n```\n\n#### Multi-select List Box\n\n`multiple` switches the component to a scrollable list that allows zero or more simultaneous selections. Use `rows` to control how many rows are visible without scrolling (`size` sets the height of the field). Mark the options to preselect with `selected`, as in a native `<select multiple>`. The form submits an entry per selected option under `name`, and `values` in the `mdsInputSelectChange` detail lists them all; `value` holds only the first one, as `select.value` does.\n\n```html\n<mds-input-select name=\"competenze\" multiple rows=\"4\">\n <option value=\"js\" selected>JavaScript</option>\n <option value=\"ts\" selected>TypeScript</option>\n <option value=\"css\">CSS</option>\n <option value=\"html\">HTML</option>\n <option value=\"react\">React</option>\n</mds-input-select>\n```\n\n#### Grouped Options via `<optgroup>`\n\nThe default slot also accepts `<optgroup>` elements. Use them to group related options under a visible label.\n\n```html\n<mds-input-select name=\"comune\" placeholder=\"Seleziona comune...\">\n <optgroup label=\"Lombardia\">\n <option value=\"MI\">Milano</option>\n <option value=\"BS\">Brescia</option>\n </optgroup>\n <optgroup label=\"Veneto\">\n <option value=\"VE\">Venezia</option>\n <option value=\"VR\">Verona</option>\n </optgroup>\n</mds-input-select>\n```\n\n#### Variant for Validation Feedback\n\nSet `variant` to one of the status values (`error`, `success`, `warning`, `info`) to communicate the validation outcome visually. Use this after a form submission or inline validation, not as decorative styling.\n\n```html\n<!-- Errore di validazione -->\n<mds-input-select name=\"tipologia\" variant=\"error\" required placeholder=\"Seleziona tipologia...\">\n <option value=\"A\">Tipo A</option>\n <option value=\"B\">Tipo B</option>\n</mds-input-select>\n\n<!-- Selezione valida confermata -->\n<mds-input-select name=\"tipologia\" variant=\"success\" value=\"A\">\n <option value=\"A\">Tipo A</option>\n <option value=\"B\">Tipo B</option>\n</mds-input-select>\n```\n\n#### Styling Customization\n\nCustomize the component only through its documented `--mds-input-select-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles ([`agents/color.md`](../../../../agents/color.md)) so dark mode and high-contrast modes continue to work correctly. `--mds-input-select-variant-color-rgb` takes a bare RGB triplet (`var(--magma-<role>)`, no `rgb()`); the other properties take a color (`rgb(var(--magma-<role>))`). `--mds-input-select-ring` is the ring at rest: on hover and focus the select draws its own 3px ring in the variant color, so the focus stays visible whatever the ring at rest, in dark mode and with more contrast too; change its color through `--mds-input-select-variant-color-rgb`.\n\n```css\n.sidebar-filter mds-input-select {\n --mds-input-select-variant-color-rgb: var(--magma-accent-emphasis);\n --mds-input-select-arrow-icon-hover-color: rgb(var(--magma-accent-fg));\n --mds-input-select-arrow-icon-hover-background-color: rgb(var(--magma-accent-surface-hover));\n --mds-input-select-ring: 0 0 0 2px rgb(var(--magma-accent-emphasis) / 0.8);\n}\n```\n",
|
|
15891
16035
|
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Slot Non-Option Elements\n\nThe default slot is reserved for `<option>` and `<optgroup>` elements. The component clones slot children into the inner `<select>`; any other element is copied verbatim and makes the native select malformed.\n\n```html\n<!-- INCORRECT -->\n<mds-input-select name=\"categoria\">\n <div class=\"option-group\">\n <span>Notizie</span>\n <span>Eventi</span>\n </div>\n</mds-input-select>\n\n<!-- CORRECT -->\n<mds-input-select name=\"categoria\" placeholder=\"Seleziona...\">\n <option value=\"news\">Notizie</option>\n <option value=\"eventi\">Eventi</option>\n</mds-input-select>\n```\n\n#### Do Not Listen to the Native `change` Event\n\n`<mds-input-select>` wraps a shadow-DOM `<select>`; the native `change` event does not bubble out of shadow DOM reliably. Always listen to the documented `mdsInputSelectChange` custom event instead.\n\n```html\n<!-- INCORRECT -->\n<mds-input-select id=\"sel\" name=\"tipo\"></mds-input-select>\n<script>\n document.getElementById('sel').addEventListener('change', (e) => {\n console.log(e.target.value); // may be undefined or stale\n });\n</script>\n\n<!-- CORRECT -->\n<mds-input-select id=\"sel\" name=\"tipo\"></mds-input-select>\n<script>\n document.getElementById('sel').addEventListener('mdsInputSelectChange', (e) => {\n console.log(e.detail.value);\n });\n</script>\n```\n\n#### Do Not Use `variant` for Decorative Styling\n\n`variant` maps to `ThemeStatusVariantType` (`error`, `success`, `warning`, `info`). It is meant to communicate a validation outcome, not to apply a brand color. Using a status variant to make the component visually match a section's color theme misleads users about the control's validation state.\n\n```html\n<!-- INCORRECT - using 'info' just for a blue accent -->\n<mds-input-select name=\"argomento\" variant=\"info\">\n <option value=\"A\">Argomento A</option>\n</mds-input-select>\n\n<!-- CORRECT - set variant only to reflect real validation state -->\n<mds-input-select name=\"argomento\" variant=\"error\" required placeholder=\"Obbligatorio\">\n <option value=\"A\">Argomento A</option>\n</mds-input-select>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Inner `<select>`\n\nThe supported customization surface is the 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(--magma-danger-emphasis));\n --mds-input-select-variant-color-rgb: var(--magma-danger-emphasis);\n}\nmds-input-select::part(select) {\n font-size: 1rem;\n}\n```\n\n#### Do Not Set `placeholder` When You Need a Real Default Selection\n\n`placeholder` injects an empty-value leading option that disappears from valid choices once `required` is set. If you want the component to open with a specific option pre-selected, use `value` or `default-value` instead.\n\n```html\n<!-- INCORRECT - a real value supplied as placeholder text -->\n<mds-input-select name=\"priorita\" placeholder=\"Media\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n\n<!-- CORRECT - use value to pre-select a real option -->\n<mds-input-select name=\"priorita\" value=\"media\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n```\n\n#### Do Not Replace with a Raw `<select>`\n\n`<mds-input-select>` provides theming, accessible status tips, form-reset integration, and dark/high-contrast support. Reaching for a plain `<select>` bypasses all of that and breaks visual consistency across themes.\n\n```html\n<!-- INCORRECT -->\n<select name=\"categoria\" class=\"form-select\">\n <option value=\"\">Seleziona...</option>\n <option value=\"A\">Categoria A</option>\n</select>\n\n<!-- CORRECT -->\n<mds-input-select name=\"categoria\" placeholder=\"Seleziona...\">\n <option value=\"A\">Categoria A</option>\n</mds-input-select>\n```\n"
|
|
15892
16036
|
},
|
|
15893
16037
|
"props": [
|
|
@@ -16151,7 +16295,7 @@
|
|
|
16151
16295
|
"setter": false
|
|
16152
16296
|
},
|
|
16153
16297
|
{
|
|
16154
|
-
"name": "
|
|
16298
|
+
"name": "rows",
|
|
16155
16299
|
"type": "number | undefined",
|
|
16156
16300
|
"complexType": {
|
|
16157
16301
|
"original": "number",
|
|
@@ -16159,9 +16303,9 @@
|
|
|
16159
16303
|
"references": {}
|
|
16160
16304
|
},
|
|
16161
16305
|
"mutable": false,
|
|
16162
|
-
"attr": "
|
|
16306
|
+
"attr": "rows",
|
|
16163
16307
|
"reflectToAttr": true,
|
|
16164
|
-
"docs": "
|
|
16308
|
+
"docs": "The number of option rows the list shows at once, as the `size` of a native `<select>`:\nwith `multiple`, or above `1`, the select shows a list box",
|
|
16165
16309
|
"docsTags": [
|
|
16166
16310
|
{
|
|
16167
16311
|
"name": "default",
|
|
@@ -16182,6 +16326,57 @@
|
|
|
16182
16326
|
"getter": false,
|
|
16183
16327
|
"setter": false
|
|
16184
16328
|
},
|
|
16329
|
+
{
|
|
16330
|
+
"name": "size",
|
|
16331
|
+
"type": "\"lg\" | \"md\" | \"sm\" | number | undefined",
|
|
16332
|
+
"complexType": {
|
|
16333
|
+
"original": "InputSizeType | number",
|
|
16334
|
+
"resolved": "\"lg\" | \"md\" | \"sm\" | number | undefined",
|
|
16335
|
+
"references": {
|
|
16336
|
+
"InputSizeType": {
|
|
16337
|
+
"location": "import",
|
|
16338
|
+
"path": "@type/input",
|
|
16339
|
+
"id": "src/type/input.ts::InputSizeType",
|
|
16340
|
+
"referenceLocation": "InputSizeType"
|
|
16341
|
+
}
|
|
16342
|
+
}
|
|
16343
|
+
},
|
|
16344
|
+
"mutable": false,
|
|
16345
|
+
"attr": "size",
|
|
16346
|
+
"reflectToAttr": true,
|
|
16347
|
+
"docs": "Specifies the height of the field, the same as `mds-button`: `sm` 28px, `md` 36px, `lg` 48px.\nA number is still read as `rows`, the row count this prop used to set: that use is deprecated\nand goes in the next major",
|
|
16348
|
+
"docsTags": [
|
|
16349
|
+
{
|
|
16350
|
+
"name": "default",
|
|
16351
|
+
"text": "'lg'"
|
|
16352
|
+
}
|
|
16353
|
+
],
|
|
16354
|
+
"default": "'lg'",
|
|
16355
|
+
"values": [
|
|
16356
|
+
{
|
|
16357
|
+
"value": "lg",
|
|
16358
|
+
"type": "string"
|
|
16359
|
+
},
|
|
16360
|
+
{
|
|
16361
|
+
"value": "md",
|
|
16362
|
+
"type": "string"
|
|
16363
|
+
},
|
|
16364
|
+
{
|
|
16365
|
+
"value": "sm",
|
|
16366
|
+
"type": "string"
|
|
16367
|
+
},
|
|
16368
|
+
{
|
|
16369
|
+
"type": "number"
|
|
16370
|
+
},
|
|
16371
|
+
{
|
|
16372
|
+
"type": "undefined"
|
|
16373
|
+
}
|
|
16374
|
+
],
|
|
16375
|
+
"optional": true,
|
|
16376
|
+
"required": false,
|
|
16377
|
+
"getter": false,
|
|
16378
|
+
"setter": false
|
|
16379
|
+
},
|
|
16185
16380
|
{
|
|
16186
16381
|
"name": "value",
|
|
16187
16382
|
"type": "null | number | string | undefined",
|
|
@@ -16361,7 +16556,7 @@
|
|
|
16361
16556
|
{
|
|
16362
16557
|
"name": "--mds-input-select-ring",
|
|
16363
16558
|
"annotation": "prop",
|
|
16364
|
-
"docs": "
|
|
16559
|
+
"docs": "Ring applied around the select at rest; hover and focus draw a 3px ring in the variant color"
|
|
16365
16560
|
},
|
|
16366
16561
|
{
|
|
16367
16562
|
"name": "--mds-input-select-shadow",
|
|
@@ -16421,7 +16616,7 @@
|
|
|
16421
16616
|
}
|
|
16422
16617
|
],
|
|
16423
16618
|
"usage": {
|
|
16424
|
-
"1. Description": "The `<mds-input-switch>` web component is the binary/selectable input control of the Magma Design System. A single tag covers three native primitives - it renders as a toggle switch by default and re-renders as a native `checkbox` or `radio` depending on `type`, wrapping `<input type=\"checkbox|radio\">` with form association, accessibility, and iconography handled natively.\n\n#### Semantic Behavior\n\n- **Type-driven rendering**: `type` selects the visual primitive. `'switch'` (default) renders the sliding toggle; `'checkbox'` and `'radio'` render the corresponding native control.\n- **Form association**: The host participates in a `<form>` natively - the form value is `value` while `checked` and enabled, nothing otherwise, and it follows every change of `checked`, `value` or `disabled`, by the user or by code. A form reset brings back the `checked` state of load, like a native input.\n- **Radio grouping**: When `type=\"radio\"`, checking one instance, by the user or by code, unchecks the other radios with the same `name` in the same form (or, outside a form, in the same document or shadow root), as native radios do, so the group submits one value. A radio without a `name` is a group of its own.\n- **Checked / indeterminate**: `checked` reflects selection; toggling it always clears `indeterminate`. The indeterminate glyph is only meaningful for `checkbox`.\n- **Disabled state**: Blocks interaction and clears the submitted form value while disabled. A disabled `<fieldset>` around the component does the same, as it does a native input.\n- **Keyboard operable**: The control responds to keyboard activation in addition to pointer clicks.\n- **Accessibility**: The control exposes a localized accessible label (\"select\"/\"unselect\") derived from slotted text (it/en/es/el).\n- **Change event**: `mdsInputSwitchChange` fires with `{ name, checked, value }` whenever the user changes the selection; setting `checked` from code does not emit it.\n- **Default slot**: The default slot is the visible text label rendered beside the control; when empty, the label region collapses.\n\n#### Properties & Visual Configurations\n\n- **`type`** is the primary configuration: pick `'switch'` for on/off settings, `'checkbox'` for multi-select selections, `'radio'` for mutually exclusive choices within a `name` group.\n- **`explicit`** applies only to `type=\"switch\"`: it surfaces a check/remove glyph inside the toggle knob so the on/off state is readable without relying on color alone.\n- **`size`** (`'sm'` / `'md'` / `'lg'`) scales the toggle and is honored only when `type=\"switch\"`.\n- **`icon`** overrides the default checked glyph (checkbox/radio variants); leave empty to use the type's built-in icon set.\n\n#### Other behavioral props\n\n- **`typography`** and **`variant`** style the slotted text label; they map to the shared typography ladders rather than the system tone/variant ladder defined in [`agents/variants.md`](../../../../agents/variants.md).\n",
|
|
16619
|
+
"1. Description": "The `<mds-input-switch>` web component is the binary/selectable input control of the Magma Design System. A single tag covers three native primitives - it renders as a toggle switch by default and re-renders as a native `checkbox` or `radio` depending on `type`, wrapping `<input type=\"checkbox|radio\">` with form association, accessibility, and iconography handled natively.\n\n#### Semantic Behavior\n\n- **Type-driven rendering**: `type` selects the visual primitive. `'switch'` (default) renders the sliding toggle, whose knob slides only when `checked` changes (by the user or by code) and is already in place on load or when shown again after being hidden; `'checkbox'` and `'radio'` render the corresponding native control.\n- **Form association**: The host participates in a `<form>` natively - the form value is `value` while `checked` and enabled, nothing otherwise, and it follows every change of `checked`, `value` or `disabled`, by the user or by code. A form reset brings back the `checked` state of load, like a native input.\n- **Radio grouping**: When `type=\"radio\"`, checking one instance, by the user or by code, unchecks the other radios with the same `name` in the same form (or, outside a form, in the same document or shadow root), as native radios do, so the group submits one value. A radio without a `name` is a group of its own.\n- **Checked / indeterminate**: `checked` reflects selection; toggling it always clears `indeterminate`. The indeterminate glyph is only meaningful for `checkbox`.\n- **Disabled state**: Blocks interaction and clears the submitted form value while disabled. A disabled `<fieldset>` around the component does the same, as it does a native input.\n- **Keyboard operable**: The control responds to keyboard activation in addition to pointer clicks.\n- **Accessibility**: The control exposes a localized accessible label (\"select\"/\"unselect\") derived from slotted text (it/en/es/el).\n- **Change event**: `mdsInputSwitchChange` fires with `{ name, checked, value }` whenever the user changes the selection; setting `checked` from code does not emit it.\n- **Default slot**: The default slot is the visible text label rendered beside the control; when empty, the label region collapses.\n\n#### Properties & Visual Configurations\n\n- **`type`** is the primary configuration: pick `'switch'` for on/off settings, `'checkbox'` for multi-select selections, `'radio'` for mutually exclusive choices within a `name` group.\n- **`explicit`** applies only to `type=\"switch\"`: it surfaces a check/remove glyph inside the toggle knob so the on/off state is readable without relying on color alone.\n- **`size`** (`'sm'` / `'md'` / `'lg'`) scales the toggle and is honored only when `type=\"switch\"`.\n- **`icon`** overrides the default checked glyph (checkbox/radio variants); leave empty to use the type's built-in icon set.\n\n#### Other behavioral props\n\n- **`typography`** and **`variant`** style the slotted text label; they map to the shared typography ladders rather than the system tone/variant ladder defined in [`agents/variants.md`](../../../../agents/variants.md).\n",
|
|
16425
16620
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-input-switch>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Toggle Switch with a Text Label\n\nThe canonical form. Slot a plain text string as the visible label. The component collapses the label region automatically when the slot is empty.\n\n```html\n<mds-input-switch name=\"notifiche\" value=\"1\">Notifiche via e-mail</mds-input-switch>\n```\n\n#### Pre-selected and Disabled States\n\nUse `checked` to pre-select the control on load. Use `disabled` to block interaction. Both are boolean attributes - remove them to turn them off; never write `checked=\"false\"` or `disabled=\"false\"`.\n\n```html\n<!-- Pre-selected -->\n<mds-input-switch name=\"newsletter\" value=\"1\" checked>Iscrizione alla newsletter</mds-input-switch>\n\n<!-- Disabled and unchecked -->\n<mds-input-switch name=\"sms\" value=\"1\" disabled>Notifiche via SMS (non disponibili)</mds-input-switch>\n\n<!-- Disabled and checked -->\n<mds-input-switch name=\"email\" value=\"1\" checked disabled>Notifiche via e-mail (obbligatorio)</mds-input-switch>\n```\n\n#### Explicit Icon Mode\n\nAdd `explicit` to surface a check/remove glyph inside the toggle knob. This makes the on/off state readable without relying on color alone, which is required in high-contrast contexts. Only effective when `type=\"switch\"`.\n\n```html\n<mds-input-switch name=\"modalita\" value=\"1\" explicit>Modalita scura</mds-input-switch>\n<mds-input-switch name=\"animazioni\" value=\"1\" explicit checked>Animazioni ridotte</mds-input-switch>\n```\n\n#### Sizing the Toggle\n\nUse the `size` prop to scale the switch knob. Sizing only applies to `type=\"switch\"`.\n\n```html\n<mds-input-switch name=\"sm\" value=\"1\" size=\"sm\">Piccolo</mds-input-switch>\n<mds-input-switch name=\"md\" value=\"1\" size=\"md\">Medio (predefinito)</mds-input-switch>\n<mds-input-switch name=\"lg\" value=\"1\" size=\"lg\">Grande</mds-input-switch>\n```\n\n#### Checkbox Type\n\nSet `type=\"checkbox\"` for multi-select use cases. The component renders the standard checkbox glyph set; `indeterminate` shows the partial-selection glyph, which is meaningful only for this type.\n\n```html\n<!-- Basic checkboxes -->\n<mds-input-switch type=\"checkbox\" name=\"opt\" value=\"a\">Opzione A</mds-input-switch>\n<mds-input-switch type=\"checkbox\" name=\"opt\" value=\"b\" checked>Opzione B</mds-input-switch>\n\n<!-- Indeterminate (parent of a mixed selection) -->\n<mds-input-switch type=\"checkbox\" name=\"tutti\" value=\"all\" indeterminate>Seleziona tutto</mds-input-switch>\n```\n\n#### Radio Group\n\nSet `type=\"radio\"` and share the same `name` across instances. Checking one automatically unchecks the others with the same name in the same form, and the form submits the value of the checked one.\n\n```html\n<mds-input-switch type=\"radio\" name=\"piano\" value=\"base\">Piano base</mds-input-switch>\n<mds-input-switch type=\"radio\" name=\"piano\" value=\"pro\" checked>Piano Pro</mds-input-switch>\n<mds-input-switch type=\"radio\" name=\"piano\" value=\"enterprise\">Piano Enterprise</mds-input-switch>\n```\n\n#### Form Participation\n\n`<mds-input-switch>` is form-associated. The form receives `value` when `checked`; if unchecked, no value is submitted. A form reset brings back the `checked` state each switch had at load.\n\n```html\n<form action=\"/preferenze\" method=\"post\">\n <mds-input-switch name=\"notifiche\" value=\"attivo\" checked>Notifiche push</mds-input-switch>\n <mds-input-switch name=\"newsletter\" value=\"attivo\">Newsletter settimanale</mds-input-switch>\n <mds-button type=\"submit\" label=\"Salva preferenze\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Listening to Changes\n\nListen for the `mdsInputSwitchChange` event - it carries `{ name, checked, value }` in `event.detail`. Do not listen for the native `change` event; it does not bubble out of Shadow DOM reliably.\n\n```html\n<mds-input-switch id=\"toggle\" name=\"tema\" value=\"scuro\">Tema scuro</mds-input-switch>\n\n<script>\n document.querySelector('#toggle').addEventListener('mdsInputSwitchChange', (e) => {\n console.log(e.detail.name, e.detail.checked, e.detail.value);\n });\n</script>\n```\n\n#### Custom Checked Icon (Checkbox / Radio)\n\nSet `icon` to any slug from the Magma icon library to override the default checked glyph for `type=\"checkbox\"` or `type=\"radio\"`. Leave `icon` empty to use the built-in glyph.\n\n```html\n<mds-input-switch type=\"checkbox\" name=\"preferito\" value=\"1\" icon=\"mi/baseline/star\" checked>\n Segna come preferito\n</mds-input-switch>\n```\n\n#### Typography Customization of the Label\n\n`typography` and `variant` style the slotted text label and map to the shared typography ladder - not the tone/variant system.\n\n```html\n<mds-input-switch name=\"opzione\" value=\"1\" typography=\"caption\">Testo piccolo</mds-input-switch>\n<mds-input-switch name=\"lettura\" value=\"1\" typography=\"paragraph\" variant=\"read\">Testo di lettura</mds-input-switch>\n```\n\n#### CSS Custom Property Customization\n\nStyle the switch only through the documented `--mds-input-switch-*` CSS custom properties. Use the semantic color roles via `rgb(var(--magma-<role>))` ([`agents/color.md`](../../../../agents/color.md)) so dark mode and high-contrast modes keep working.\n\n```css\n.settings-panel mds-input-switch {\n --mds-input-switch-box-color-enabled-checked: rgb(var(--magma-success-emphasis));\n --mds-input-switch-toggle-color-enabled-checked: rgb(var(--magma-success-on-emphasis));\n --mds-input-switch-duration: 200ms;\n --mds-input-switch-toggle-size: var(--mds-input-switch-toggle-size-lg);\n}\n```\n",
|
|
16426
16621
|
"3. Antipattern": "Common incorrect uses of `<mds-input-switch>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Set Boolean Props to the String \"false\"\n\n`checked`, `disabled`, `explicit`, and `indeterminate` are boolean attributes. Stencil reads `\"false\"` as `false` and, since all four are reflected, removes the attribute at the first render, so this happens to work; but the markup says the opposite of what it does, and on a prop that is not reflected the attribute stays in the DOM, where `[attr]` selectors still match it. Remove the attribute entirely to turn it off.\n\n```html\n<!-- INCORRECT -->\n<mds-input-switch checked=\"false\" disabled=\"false\">Notifiche</mds-input-switch>\n\n<!-- CORRECT -->\n<mds-input-switch>Notifiche</mds-input-switch>\n```\n\n#### Do Not Use a Native `<input>` Instead of `<mds-input-switch>`\n\nReplacing the component with a raw `<input type=\"checkbox\">` or `<input type=\"radio\">` bypasses the design system's theming, accessibility defaults, label layout, and form integration.\n\n```html\n<!-- INCORRECT -->\n<label>\n <input type=\"checkbox\" name=\"notifiche\" value=\"1\"> Notifiche via e-mail\n</label>\n\n<!-- CORRECT -->\n<mds-input-switch name=\"notifiche\" value=\"1\">Notifiche via e-mail</mds-input-switch>\n```\n\n#### Do Not Use `explicit` or `size` with `type=\"checkbox\"` or `type=\"radio\"`\n\n`explicit` surfaces a glyph inside the switch knob and `size` scales the knob - both are only honored when `type=\"switch\"`. They are silently ignored on other types.\n\n```html\n<!-- INCORRECT -->\n<mds-input-switch type=\"checkbox\" name=\"opt\" value=\"1\" explicit size=\"lg\">Opzione</mds-input-switch>\n\n<!-- CORRECT -->\n<mds-input-switch type=\"checkbox\" name=\"opt\" value=\"1\">Opzione</mds-input-switch>\n\n<!-- correct use of explicit and size: only with type=\"switch\" -->\n<mds-input-switch type=\"switch\" name=\"opt\" value=\"1\" explicit size=\"lg\">Opzione</mds-input-switch>\n```\n\n#### Do Not Listen for Native `change` Instead of `mdsInputSwitchChange`\n\nThe component stops and prevents the native `change` event internally. Listen for the documented `mdsInputSwitchChange` event, which carries `{ name, checked, value }` in `event.detail`.\n\n```html\n<!-- INCORRECT -->\n<mds-input-switch id=\"toggle\" name=\"tema\" value=\"scuro\">Tema scuro</mds-input-switch>\n<script>\n document.querySelector('#toggle').addEventListener('change', handler);\n</script>\n\n<!-- CORRECT -->\n<mds-input-switch id=\"toggle\" name=\"tema\" value=\"scuro\">Tema scuro</mds-input-switch>\n<script>\n document.querySelector('#toggle').addEventListener('mdsInputSwitchChange', (e) => {\n console.log(e.detail.checked);\n });\n</script>\n```\n\n#### Do Not Use `indeterminate` on `type=\"switch\"` or `type=\"radio\"`\n\nThe indeterminate glyph (`indeterminate-check-box`) is part of the checkbox icon variant only. Setting `indeterminate` on a switch has no visual effect, on a radio it blanks the radio glyph, and on both it misleads consumers about the control state.\n\n```html\n<!-- INCORRECT -->\n<mds-input-switch type=\"switch\" name=\"opt\" value=\"1\" indeterminate>Tutti i permessi</mds-input-switch>\n\n<!-- CORRECT -->\n<mds-input-switch type=\"checkbox\" name=\"tutti\" value=\"all\" indeterminate>Seleziona tutto</mds-input-switch>\n```\n\n#### Do Not Omit `name` in a Radio Group\n\nWithout a shared `name`, the radios do not form a group: as with native radios, each nameless radio is a group of its own, so several can be checked at once, and none of them is submitted with the form.\n\n```html\n<!-- INCORRECT -->\n<mds-input-switch type=\"radio\" value=\"a\" checked>Opzione A</mds-input-switch>\n<mds-input-switch type=\"radio\" value=\"b\">Opzione B</mds-input-switch>\n\n<!-- CORRECT -->\n<mds-input-switch type=\"radio\" name=\"scelta\" value=\"a\" checked>Opzione A</mds-input-switch>\n<mds-input-switch type=\"radio\" name=\"scelta\" value=\"b\">Opzione B</mds-input-switch>\n```\n\n#### Do Not Customize with Undocumented CSS Parts or Internal Selectors\n\nThe only supported customization surface is the documented `--mds-input-switch-*` CSS custom properties. Targeting shadow internals via `::part()` on undocumented parts or via `>>>` will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-input-switch >>> .switch {\n border-radius: 4px;\n}\nmds-input-switch::part(toggle) {\n box-shadow: none;\n}\n\n/* CORRECT */\nmds-input-switch {\n --mds-input-switch-box-color-enabled-checked: rgb(var(--magma-success-emphasis));\n --mds-input-switch-duration: 150ms;\n}\n```\n"
|
|
16427
16622
|
},
|
|
@@ -19062,7 +19257,7 @@
|
|
|
19062
19257
|
}
|
|
19063
19258
|
],
|
|
19064
19259
|
"usage": {
|
|
19065
|
-
"1. Description": "The `<mds-list>` web component is the structural container of the Magma Design System list family. It is a thin compound parent that groups one or more `<mds-list-item>` children and replaces the native `<ul>`/`<ol>` primitive with an accessible, design-system-aware wrapper.\n\n#### Semantic Behavior\n\n- **List role**: Exposes the group as a semantic list to assistive technology regardless of the surrounding markup.\n- **Compound parent**: Acts purely as the container; the visual rows (leading glyph and text) live in the slotted `<mds-list-item>` children.\n- **Default slot is structural**: The default slot is meant to receive `<mds-list-item>` element(s) rather than free text.\n\n#### Properties & Visual Configurations\n\nThis component exposes no configurable props; it carries no `variant`, `tone`,
|
|
19260
|
+
"1. Description": "The `<mds-list>` web component is the structural container of the Magma Design System list family. It is a thin compound parent that groups one or more `<mds-list-item>` children and replaces the native `<ul>`/`<ol>` primitive with an accessible, design-system-aware wrapper.\n\n#### Semantic Behavior\n\n- **List role**: Exposes the group as a semantic list to assistive technology regardless of the surrounding markup.\n- **Compound parent**: Acts purely as the container; the visual rows (leading glyph and text) live in the slotted `<mds-list-item>` children.\n- **Default slot is structural**: The default slot is meant to receive `<mds-list-item>` element(s) rather than free text.\n\n#### Properties & Visual Configurations\n\nThis component exposes no configurable props; it carries no `variant`, `tone`, `size` or text colour of its own: the items take the colour of the container, and a class such as `text-fg-muted` on `<mds-list>` makes the whole list secondary. All appearance and behavior are delegated to the slotted `<mds-list-item>` children. For the shared ladders that govern the children, see [`agents/variants.md`](../../../../agents/variants.md).\n",
|
|
19066
19261
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-list>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the typography scale documented in [`agents/typography.md`](../../../../agents/typography.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic List\n\nThe canonical form. Place `<mds-list-item>` children directly inside `<mds-list>`. Each item renders a leading bullet glyph (the default list-dot icon) and the slotted text.\n\n```html\n<mds-list>\n <mds-list-item>Rinnova la licenza annuale</mds-list-item>\n <mds-list-item>Verifica i dati di fatturazione</mds-list-item>\n <mds-list-item>Scarica la ricevuta in PDF</mds-list-item>\n</mds-list>\n```\n\n#### Overriding the Item Icon\n\nPass an icon slug to `<mds-list-item>` via the `icon` prop to replace the default bullet with a meaningful glyph. Leave the prop unset to keep the standard dot.\n\n```html\n<mds-list>\n <mds-list-item icon=\"mi/baseline/check-circle\">Profilo aggiornato</mds-list-item>\n <mds-list-item icon=\"mi/baseline/check-circle\">Password modificata</mds-list-item>\n <mds-list-item icon=\"mi/baseline/pending\">Verifica email in attesa</mds-list-item>\n</mds-list>\n```\n\n#### Choosing the Typography Scale\n\nUse the `typography` prop on each `<mds-list-item>` to match the visual density of the surrounding content. The default is `detail`; use `paragraph` for body-copy contexts and `caption` or `tip` for compact secondary lists.\n\n```html\n<!-- Body-copy density - long paragraphs nearby -->\n<mds-list>\n <mds-list-item typography=\"paragraph\">Seleziona il piano adatto alle tue esigenze</mds-list-item>\n <mds-list-item typography=\"paragraph\">Inserisci i dati di pagamento</mds-list-item>\n <mds-list-item typography=\"paragraph\">Conferma l'ordine e ricevi la ricevuta</mds-list-item>\n</mds-list>\n\n<!-- Compact secondary list -->\n<mds-list>\n <mds-list-item typography=\"caption\">Aggiornato il 01/06/2026</mds-list-item>\n <mds-list-item typography=\"caption\">Versione 3.2.1</mds-list-item>\n</mds-list>\n```\n\n#### Reading Variant for Long-Form Content\n\nSet `variant=\"read\"` when list items appear inside a reading-optimized context (article, tutorial, legal text). Use the default `variant=\"info\"` for compact informational lists.\n\n```html\n<mds-list>\n <mds-list-item typography=\"paragraph\" variant=\"read\">\n Il servizio e' disponibile per tutti gli enti pubblici italiani\n </mds-list-item>\n <mds-list-item typography=\"paragraph\" variant=\"read\">\n L'accesso avviene tramite credenziali SPID o CIE\n </mds-list-item>\n <mds-list-item typography=\"paragraph\" variant=\"read\">\n I dati sono trattati in conformita' al GDPR\n </mds-list-item>\n</mds-list>\n```\n\n#### Mixed Icon and Default Bullet in the Same List\n\nYou can mix items with an explicit `icon` and items that fall back to the default bullet within the same `<mds-list>`. Each item is independent.\n\n```html\n<mds-list>\n <mds-list-item icon=\"mi/baseline/warning\">Modulo non compilato</mds-list-item>\n <mds-list-item>Campo facoltativo ignorato</mds-list-item>\n <mds-list-item icon=\"mi/baseline/error\">Firma digitale mancante</mds-list-item>\n</mds-list>\n```\n\n#### Styling Customization via CSS Custom Property\n\nAdjust icon spacing through the documented `--mds-list-item-icon-margin` CSS custom property. Set it on the `<mds-list-item>` host or on a parent selector; use Magma spacing tokens.\n\n```css\n.sidebar-checklist mds-list-item {\n --mds-list-item-icon-margin: 0 calc(var(--spacing) * 300) 0 0;\n}\n```\n\n#### Shadow Part Customization\n\nReach the icon or text nodes through the documented `::part(icon)` and `::part(text)` parts of `<mds-list-item>` when CSS custom properties are insufficient. Do not pierce the shadow DOM via `>>>` or undocumented selectors.\n\n```css\n/* Tint the leading icon of every item in a warning context */\n.alert-list mds-list-item::part(icon) {\n fill: rgb(var(--magma-warning-fg));\n}\n```\n",
|
|
19067
19262
|
"3. Antipattern": "Common incorrect uses of `<mds-list>` and `<mds-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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Replace `<mds-list>` with a Native `<ul>` or `<ol>`\n\nUsing a raw list element bypasses the design-system layout, typography defaults, and FOUC handling built into the component pair.\n\n```html\n<!-- INCORRECT -->\n<ul>\n <li>Primo elemento</li>\n <li>Secondo elemento</li>\n</ul>\n\n<!-- CORRECT -->\n<mds-list>\n <mds-list-item>Primo elemento</mds-list-item>\n <mds-list-item>Secondo elemento</mds-list-item>\n</mds-list>\n```\n\n#### Do Not Put HTML Elements in the Default Slot of `<mds-list-item>`\n\nThe default slot of `<mds-list-item>` accepts a plain text string only; placing HTML elements or other components there is explicitly discouraged in the component's API and can break layout and compound-component communication.\n\n```html\n<!-- INCORRECT -->\n<mds-list>\n <mds-list-item>\n <strong>Allegato 1</strong> - Contratto firmato\n </mds-list-item>\n</mds-list>\n\n<!-- CORRECT -->\n<mds-list>\n <mds-list-item>Allegato 1 - Contratto firmato</mds-list-item>\n</mds-list>\n```\n\n#### Do Not Use `<mds-list-item>` Outside `<mds-list>`\n\n`<mds-list-item>` is a compound child designed to work exclusively inside `<mds-list>`. Using it standalone or wrapping it in a plain `<div>` breaks the accessible list context.\n\n```html\n<!-- INCORRECT -->\n<div class=\"my-list\">\n <mds-list-item>Voce autonoma</mds-list-item>\n</div>\n\n<!-- CORRECT -->\n<mds-list>\n <mds-list-item>Voce autonoma</mds-list-item>\n</mds-list>\n```\n\n#### Do Not Slot `<mds-icon>` to Override the Bullet\n\nThe `icon` prop on `<mds-list-item>` is the supported way to change the leading glyph. Slotting `<mds-icon>` into the default slot puts it inline in a text-only slot, misaligned, while the default bullet still renders.\n\n```html\n<!-- INCORRECT -->\n<mds-list>\n <mds-list-item>\n <mds-icon name=\"mi/baseline/check\"></mds-icon>\n Voce completata\n </mds-list-item>\n</mds-list>\n\n<!-- CORRECT -->\n<mds-list>\n <mds-list-item icon=\"mi/baseline/check\">Voce completata</mds-list-item>\n</mds-list>\n```\n\n#### Do Not Add Non-Item Children Directly to `<mds-list>`\n\nThe default slot of `<mds-list>` is documented to receive `<mds-list-item>` elements. Mixing in headings, paragraphs, or other components breaks the expected structure and removes the semantic list context.\n\n```html\n<!-- INCORRECT -->\n<mds-list>\n <mds-text typography=\"h6\">Documenti richiesti</mds-text>\n <mds-list-item>Documento d'identita'</mds-list-item>\n <mds-list-item>Codice fiscale</mds-list-item>\n</mds-list>\n\n<!-- CORRECT -->\n<mds-text typography=\"h6\">Documenti richiesti</mds-text>\n<mds-list>\n <mds-list-item>Documento d'identita'</mds-list-item>\n <mds-list-item>Codice fiscale</mds-list-item>\n</mds-list>\n```\n\n#### Do Not Apply an Invalid `typography` Value to `<mds-list-item>`\n\n`mds-list-item.typography` accepts `TypographyInfoType | TypographyReadType` - the allowed values are `caption`, `detail`, `label`, `option`, `paragraph`, and `tip`. Heading values such as `h1`-`h6` or `action` are outside the type and are not checked at runtime: the inner text renders the heading style next to a bullet aligned for body text.\n\n```html\n<!-- INCORRECT -->\n<mds-list>\n <mds-list-item typography=\"h3\">Titolo non valido</mds-list-item>\n</mds-list>\n\n<!-- CORRECT -->\n<mds-list>\n <mds-list-item typography=\"paragraph\">Testo valido</mds-list-item>\n</mds-list>\n```\n"
|
|
19068
19263
|
},
|
|
@@ -19096,8 +19291,8 @@
|
|
|
19096
19291
|
}
|
|
19097
19292
|
],
|
|
19098
19293
|
"usage": {
|
|
19099
|
-
"1. Description": "The `<mds-list-item>` web component is the single entry of a Magma list, designed to be slotted exclusively inside its parent [`<mds-list>`](../mds-list/AGENTS.md). It plays the role of a native `<li>`, pairing a leading icon with a text string so that the parent `<mds-list>` can present a coherent, accessible list.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-list>`; it is not used standalone or mixed with other element types.\n- **Leading icon is always present**: The component renders an icon before its text; when no `icon` is supplied it falls back to a built-in list-dot glyph, which is decorative.\n- **Text-only default slot**: The default slot is intended for a plain text string; adding HTML elements or other components here is discouraged.\n\n#### Properties & Visual Configurations\n\n- **`typography`**: Selects the text style of the item (default `detail`), drawn from the shared typography scale; pick the value that matches the density and hierarchy of the surrounding list content.\n- **`variant`**: Refines the chosen `typography` (default `info`); use `read` for long-form reading contexts and `info` for compact informational lists.\n- **`icon`**: Overrides the default list-dot with a named icon when a list entry benefits from a meaningful leading glyph; leave unset to keep the standard bullet.\n",
|
|
19100
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-list-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the typography scale documented in [`agents/typography.md`](../../../../agents/typography.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic List with Default Bullet\n\nThe canonical form. Place one or more `<mds-list-item>` elements as direct children of [`<mds-list>`](../mds-list/AGENTS.md). Text content goes in the default slot. When no `icon` is provided the component renders the built-in list-dot glyph automatically.\n\n```html\n<mds-list>\n <mds-list-item>Pane</mds-list-item>\n <mds-list-item>Acqua</mds-list-item>\n <mds-list-item>Pasta</mds-list-item>\n</mds-list>\n```\n\n#### Typography Scale\n\nUse the `typography` prop to match the text density of the surrounding content. The default is `detail`; switch to `paragraph` for body-text contexts or `caption` / `tip` for fine-print lists.\n\n```html\n<mds-list>\n <!-- Body-text list -->\n <mds-list-item typography=\"paragraph\">Seleziona un elemento dalla lista</mds-list-item>\n <mds-list-item typography=\"paragraph\">Conferma la scelta effettuata</mds-list-item>\n <mds-list-item typography=\"paragraph\">Salva le modifiche apportate</mds-list-item>\n</mds-list>\n\n<mds-list>\n <!-- Fine-print annotation list -->\n <mds-list-item typography=\"caption\">I campi contrassegnati sono obbligatori</mds-list-item>\n <mds-list-item typography=\"caption\">La password deve contenere almeno 8 caratteri</mds-list-item>\n</mds-list>\n```\n\n#### Reading Variant\n\nUse `variant=\"read\"` for long-form reading contexts (articles, documentation); keep the default `variant=\"info\"` for compact informational lists in UI panels.\n\n```html\n<!-- Long-form reading context -->\n<mds-list>\n <mds-list-item typography=\"paragraph\" variant=\"read\">\n Il servizio e disponibile dal lunedi al venerdi, dalle 9 alle 18.\n </mds-list-item>\n <mds-list-item typography=\"paragraph\" variant=\"read\">\n Per assistenza urgente contattare il numero verde dedicato.\n </mds-list-item>\n</mds-list>\n```\n\n#### Custom Leading Icon\n\nSupply an icon slug via the `icon` prop to replace the default bullet with a meaningful glyph. Use this when each entry maps to a distinct category or action.\n\n```html\n<mds-list>\n <mds-list-item icon=\"mi/baseline/check-circle\">Account verificato</mds-list-item>\n <mds-list-item icon=\"mi/baseline/lock\">Accesso sicuro attivato</mds-list-item>\n <mds-list-item icon=\"mi/baseline/notifications\">Notifiche abilitate</mds-list-item>\n</mds-list>\n```\n\n#### Uniform Icon Across All Items\n\nWhen every item shares the same icon - for example a checklist or a feature list - set the same `icon` on each item for visual consistency.\n\n```html\n<mds-list>\n <mds-list-item icon=\"mi/baseline/check\">Supporto multilingua incluso</mds-list-item>\n <mds-list-item icon=\"mi/baseline/check\">Aggiornamenti automatici</mds-list-item>\n <mds-list-item icon=\"mi/baseline/check\">Assistenza prioritaria 24/7</mds-list-item>\n</mds-list>\n```\n\n#### Styling Customization via CSS Custom Property\n\nAdjust the icon margin through the documented `--mds-list-item-icon-margin` CSS custom property. Set it on the host or a parent selector; use Magma spacing tokens for consistency.\n\n```css\n.compact-list mds-list-item {\n --mds-list-item-icon-margin: 0 calc(var(--spacing) * 100) 0 0;\n}\n```\n\n#### Styling the Icon Part\n\nUse the documented `::part(icon)` surface to tint or resize the leading icon. Prefer Magma color tokens to keep dark-mode compatibility.\n\n```css\n.status-list mds-list-item::part(icon) {\n fill: rgb(var(--magma-success-fg));\n}\n```\n",
|
|
19294
|
+
"1. Description": "The `<mds-list-item>` web component is the single entry of a Magma list, designed to be slotted exclusively inside its parent [`<mds-list>`](../mds-list/AGENTS.md). It plays the role of a native `<li>`, pairing a leading icon with a text string so that the parent `<mds-list>` can present a coherent, accessible list.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-list>`; it is not used standalone or mixed with other element types.\n- **Leading icon is always present**: The component renders an icon before its text; when no `icon` is supplied it falls back to a built-in list-dot glyph, which is decorative.\n- **Text-only default slot**: The default slot is intended for a plain text string; adding HTML elements or other components here is discouraged.\n- **Inherited text colour**: The item sets no colour of its own: its text and its leading icon take the colour of the container, as `<mds-text>` does, so a list reads like the paragraphs around it and follows a container that sets its own colour (a tinted card, a banner). For a secondary list, set the muted role on `<mds-list>` or on its container (`text-fg-muted`).\n\n#### Properties & Visual Configurations\n\n- **`typography`**: Selects the text style of the item (default `detail`), drawn from the shared typography scale; pick the value that matches the density and hierarchy of the surrounding list content.\n- **`variant`**: Refines the chosen `typography` (default `info`); use `read` for long-form reading contexts and `info` for compact informational lists.\n- **`icon`**: Overrides the default list-dot with a named icon when a list entry benefits from a meaningful leading glyph; leave unset to keep the standard bullet.\n",
|
|
19295
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-list-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the typography scale documented in [`agents/typography.md`](../../../../agents/typography.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic List with Default Bullet\n\nThe canonical form. Place one or more `<mds-list-item>` elements as direct children of [`<mds-list>`](../mds-list/AGENTS.md). Text content goes in the default slot. When no `icon` is provided the component renders the built-in list-dot glyph automatically.\n\n```html\n<mds-list>\n <mds-list-item>Pane</mds-list-item>\n <mds-list-item>Acqua</mds-list-item>\n <mds-list-item>Pasta</mds-list-item>\n</mds-list>\n```\n\n#### Typography Scale\n\nUse the `typography` prop to match the text density of the surrounding content. The default is `detail`; switch to `paragraph` for body-text contexts or `caption` / `tip` for fine-print lists.\n\n```html\n<mds-list>\n <!-- Body-text list -->\n <mds-list-item typography=\"paragraph\">Seleziona un elemento dalla lista</mds-list-item>\n <mds-list-item typography=\"paragraph\">Conferma la scelta effettuata</mds-list-item>\n <mds-list-item typography=\"paragraph\">Salva le modifiche apportate</mds-list-item>\n</mds-list>\n\n<mds-list>\n <!-- Fine-print annotation list -->\n <mds-list-item typography=\"caption\">I campi contrassegnati sono obbligatori</mds-list-item>\n <mds-list-item typography=\"caption\">La password deve contenere almeno 8 caratteri</mds-list-item>\n</mds-list>\n```\n\n#### Reading Variant\n\nUse `variant=\"read\"` for long-form reading contexts (articles, documentation); keep the default `variant=\"info\"` for compact informational lists in UI panels.\n\n```html\n<!-- Long-form reading context -->\n<mds-list>\n <mds-list-item typography=\"paragraph\" variant=\"read\">\n Il servizio e disponibile dal lunedi al venerdi, dalle 9 alle 18.\n </mds-list-item>\n <mds-list-item typography=\"paragraph\" variant=\"read\">\n Per assistenza urgente contattare il numero verde dedicato.\n </mds-list-item>\n</mds-list>\n```\n\n#### Custom Leading Icon\n\nSupply an icon slug via the `icon` prop to replace the default bullet with a meaningful glyph. Use this when each entry maps to a distinct category or action.\n\n```html\n<mds-list>\n <mds-list-item icon=\"mi/baseline/check-circle\">Account verificato</mds-list-item>\n <mds-list-item icon=\"mi/baseline/lock\">Accesso sicuro attivato</mds-list-item>\n <mds-list-item icon=\"mi/baseline/notifications\">Notifiche abilitate</mds-list-item>\n</mds-list>\n```\n\n#### Uniform Icon Across All Items\n\nWhen every item shares the same icon - for example a checklist or a feature list - set the same `icon` on each item for visual consistency.\n\n```html\n<mds-list>\n <mds-list-item icon=\"mi/baseline/check\">Supporto multilingua incluso</mds-list-item>\n <mds-list-item icon=\"mi/baseline/check\">Aggiornamenti automatici</mds-list-item>\n <mds-list-item icon=\"mi/baseline/check\">Assistenza prioritaria 24/7</mds-list-item>\n</mds-list>\n```\n\n#### Muted List\n\nThe items take the colour of their container. When a list is secondary information (an address, a list of contacts under a title), give the muted role to `<mds-list>` or to its container rather than to each item.\n\n```html\n<mds-list class=\"text-fg-muted\">\n <mds-list-item>Via Carlo Farini 1, Santarcangelo di Romagna</mds-list-item>\n <mds-list-item>0541 628111</mds-list-item>\n</mds-list>\n```\n\n#### Styling Customization via CSS Custom Property\n\nAdjust the icon margin through the documented `--mds-list-item-icon-margin` CSS custom property. Set it on the host or a parent selector; use Magma spacing tokens for consistency.\n\n```css\n.compact-list mds-list-item {\n --mds-list-item-icon-margin: 0 calc(var(--spacing) * 100) 0 0;\n}\n```\n\n#### Styling the Icon Part\n\nUse the documented `::part(icon)` surface to tint or resize the leading icon. Prefer Magma color tokens to keep dark-mode compatibility.\n\n```css\n.status-list mds-list-item::part(icon) {\n fill: rgb(var(--magma-success-fg));\n}\n```\n",
|
|
19101
19296
|
"3. Antipattern": "Common incorrect uses of `<mds-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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-list-item>` Outside `<mds-list>`\n\n`<mds-list-item>` is a compound child; it must be a direct default-slot child of [`<mds-list>`](../mds-list/AGENTS.md). Using it standalone removes the list context that assistive technology relies on.\n\n```html\n<!-- INCORRECT -->\n<div>\n <mds-list-item>Primo elemento</mds-list-item>\n <mds-list-item>Secondo elemento</mds-list-item>\n</div>\n\n<!-- CORRECT -->\n<mds-list>\n <mds-list-item>Primo elemento</mds-list-item>\n <mds-list-item>Secondo elemento</mds-list-item>\n</mds-list>\n```\n\n#### Do Not Put HTML Elements in the Default Slot\n\nThe default slot is meant for plain text only; nested elements are not stripped, they render inline and can break layout. Use the `typography` and `variant` props to control text style instead.\n\n```html\n<!-- INCORRECT -->\n<mds-list>\n <mds-list-item>\n <strong>Titolo voce</strong>\n <small> - descrizione aggiuntiva</small>\n </mds-list-item>\n</mds-list>\n\n<!-- CORRECT -->\n<mds-list>\n <mds-list-item typography=\"detail\">Titolo voce - descrizione aggiuntiva</mds-list-item>\n</mds-list>\n```\n\n#### Do Not Slot `<mds-icon>` to Add a Leading Icon\n\nThe `icon` prop renders the glyph through the shared icon service and positions it correctly. Slotting `<mds-icon>` puts it in the text-only default slot, where it is misaligned and the default bullet still renders.\n\n```html\n<!-- INCORRECT -->\n<mds-list>\n <mds-list-item>\n <mds-icon name=\"mi/baseline/check\"></mds-icon>\n Servizio attivo\n </mds-list-item>\n</mds-list>\n\n<!-- CORRECT -->\n<mds-list>\n <mds-list-item icon=\"mi/baseline/check\">Servizio attivo</mds-list-item>\n</mds-list>\n```\n\n#### Do Not Use a `typography` Value Outside the Accepted Set\n\n`<mds-list-item>` accepts only `TypographyInfoType | TypographyReadType`: `caption`, `detail`, `label`, `option`, `paragraph`, `tip`. Heading values like `h1`-`h6` or `action` are outside the type and are not checked at runtime: the inner text renders the heading style next to a bullet aligned for body text.\n\n```html\n<!-- INCORRECT -->\n<mds-list>\n <mds-list-item typography=\"h3\">Titolo sezione</mds-list-item>\n <mds-list-item typography=\"action\">Azione</mds-list-item>\n</mds-list>\n\n<!-- CORRECT -->\n<mds-list>\n <mds-list-item typography=\"detail\">Voce elenco</mds-list-item>\n <mds-list-item typography=\"paragraph\">Descrizione estesa della voce</mds-list-item>\n</mds-list>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Icon or Text\n\nThe supported customization surface is `--mds-list-item-icon-margin` for layout and `::part(icon)` / `::part(text)` for the two documented shadow parts. Targeting internals via `>>>` or undocumented class names couples code to the implementation.\n\n```css\n/* INCORRECT */\nmds-list-item >>> .icon {\n fill: red;\n}\n\n/* CORRECT */\nmds-list-item::part(icon) {\n fill: rgb(var(--magma-danger-fg));\n}\n```\n\n#### Do Not Replace `<mds-list>` + `<mds-list-item>` with a Raw `<ul>` + `<li>`\n\nWhen a Magma list is needed, use the component pair - not raw HTML. Raw elements bypass the design-system theming, token integration, and high-contrast support.\n\n```html\n<!-- INCORRECT -->\n<ul>\n <li>Documento ricevuto</li>\n <li>In attesa di approvazione</li>\n</ul>\n\n<!-- CORRECT -->\n<mds-list>\n <mds-list-item>Documento ricevuto</mds-list-item>\n <mds-list-item>In attesa di approvazione</mds-list-item>\n</mds-list>\n```\n"
|
|
19102
19297
|
},
|
|
19103
19298
|
"props": [
|
|
@@ -19501,7 +19696,7 @@
|
|
|
19501
19696
|
}
|
|
19502
19697
|
],
|
|
19503
19698
|
"usage": {
|
|
19504
|
-
"1. Description": "The `<mds-modal>` web component is the Magma Design System overlay container for dialogs, presenting content in a windowed surface layered above the page with an optional backdrop. It is the system equivalent of the native `<dialog>` element, adding managed open/close animations, body scroll locking, positioning, and a built-in close affordance.\n\n#### Semantic Behavior\n\n- **Open state**: Visibility is driven by the `opened` prop. Setting it `true` runs the intro animation and emits `mdsModalOpen`; clearing it runs the outro animation and emits `mdsModalClose`.\n- **Programmatic close**: Exposes an async `close()` method that dismisses the modal regardless of `interaction`, mirroring the close-button action.\n- **Show/hide events**: `mdsModalShow` fires when the intro finishes (fully visible) and `mdsModalHide` when the outro finishes (fully hidden), the latter being the safe point to detach the modal to reclaim memory.\n- **Backdrop dismissal**: With `interaction=\"relaxed\"` (default) a click on the backdrop or `Esc` closes the modal; with `interaction=\"strict\"` both are ignored and only the close button, `close()` or a touch swipe (below) 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",
|
|
19699
|
+
"1. Description": "The `<mds-modal>` web component is the Magma Design System overlay container for dialogs, presenting content in a windowed surface layered above the page with an optional backdrop. It is the system equivalent of the native `<dialog>` element, adding managed open/close animations, body scroll locking, positioning, and a built-in close affordance.\n\n#### Semantic Behavior\n\n- **Open state**: Visibility is driven by the `opened` prop. Setting it `true` runs the intro animation and emits `mdsModalOpen`; clearing it runs the outro animation and emits `mdsModalClose`.\n- **Programmatic close**: Exposes an async `close()` method that dismisses the modal regardless of `interaction`, mirroring the close-button action.\n- **Show/hide events**: `mdsModalShow` fires when the intro finishes (fully visible) and `mdsModalHide` when the outro finishes (fully hidden), the latter being the safe point to detach the modal to reclaim memory.\n- **Backdrop dismissal**: With `interaction=\"relaxed\"` (default) a click on the backdrop or `Esc` closes the modal; with `interaction=\"strict\"` both are ignored and only the close button, `close()` or a touch swipe (below) 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, icon-only and named in the page language (the `lang` of `<html>`) (\"Close\"). Slotting a `window` element suppresses the built-in chrome and close button so the consumer supplies the entire surface.\n\n#### Properties & Visual Configurations\n\nThis component does not use the shared `variant` / `tone` ladders; its configuration is structural and motion-oriented.\n\n#### Other behavioral props\n\n- **`position`** sets where the window animates from and rests, from `'center'` to edge and corner anchors (`'top'`, `'bottom-left'`, etc.); edge positions also define the valid swipe-to-dismiss direction.\n- **`animation`** selects the motion style of the window: `'slide'` (default), `'3d'`, or `'custom'` (driven entirely by CSS custom properties).\n- **`interaction`** governs how forgiving dismissal is - `'relaxed'` allows backdrop clicks, `'strict'` requires the close button.\n- **`overflow`** chooses whether the component manages body scroll locking (`'auto'`) or leaves it to the consumer (`'manual'`).\n- **`hideBackdrop`** removes the dimmed overlay behind the window (shown by default).\n",
|
|
19505
19700
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-modal>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Modal with Inline Content\n\nThe simplest form: toggle `opened` from JavaScript to show the dialog. The built-in close button and backdrop dismiss the modal automatically with `interaction=\"relaxed\"` (default). React to the `mdsModalClose` event to sync your state.\n\n```html\n<mds-button id=\"btn-apri\">Apri dialogo</mds-button>\n\n<mds-modal id=\"dialogo\">\n <div class=\"p-400\">\n <mds-text>Sei sicuro di voler continuare?</mds-text>\n </div>\n</mds-modal>\n\n<script>\n const btn = document.getElementById('btn-apri');\n const modal = document.getElementById('dialogo');\n btn.addEventListener('click', () => { modal.opened = true; });\n modal.addEventListener('mdsModalClose', () => { modal.opened = undefined; });\n</script>\n```\n\n#### Fixed Header and Footer via `top` / `bottom` Slots\n\nUse the `top` slot for a sticky header and the `bottom` slot for a sticky footer (e.g. action buttons). The default slot renders scrollable body content between them.\n\n```html\n<mds-modal id=\"modifica-utente\" position=\"right\">\n <header slot=\"top\" class=\"p-400 bg-surface-overlay shadow-ring-weak\">\n <mds-text typography=\"h5\">Modifica utente</mds-text>\n </header>\n\n <div class=\"p-400 grid gap-400\">\n <mds-input-field label=\"Nome\">\n <mds-input name=\"nome\"></mds-input>\n </mds-input-field>\n <mds-input-field label=\"Cognome\">\n <mds-input name=\"cognome\"></mds-input>\n </mds-input-field>\n </div>\n\n <footer slot=\"bottom\" class=\"p-400 flex gap-300 justify-end bg-surface-overlay shadow-ring-weak\">\n <mds-button variant=\"dark\" tone=\"outline\" id=\"btn-annulla\">Annulla</mds-button>\n <mds-button variant=\"primary\" tone=\"strong\" id=\"btn-salva\">Salva</mds-button>\n </footer>\n</mds-modal>\n```\n\n#### Edge and Corner Positions\n\n`position` anchors the window to an edge or corner and drives the slide-in direction. Use `right` or `left` for side panels, `bottom` for mobile drawers.\n\n```html\n<!-- Side panel from the right (default in most app shells) -->\n<mds-modal id=\"pannello-laterale\" position=\"right\">\n <div class=\"p-400\">\n <mds-text>Dettagli del documento</mds-text>\n </div>\n</mds-modal>\n\n<!-- Drawer from the bottom (mobile) -->\n<mds-modal id=\"drawer-mobile\" position=\"bottom\">\n <div class=\"p-400\">\n <mds-text>Azioni disponibili</mds-text>\n </div>\n</mds-modal>\n```\n\n#### Strict Interaction Mode\n\nSet `interaction=\"strict\"` when the user must explicitly confirm or cancel before the dialog closes - for example, a form with unsaved changes. Backdrop clicks and `Esc` are ignored; only the close button or the `close()` method can dismiss the modal (a touch swipe still closes it).\n\n```html\n<mds-modal id=\"conferma-elimina\" interaction=\"strict\">\n <div class=\"p-400 grid gap-400\">\n <mds-text typography=\"h5\">Eliminare il documento?</mds-text>\n <mds-text>Questa operazione non e' reversibile.</mds-text>\n <div class=\"flex gap-300 justify-end\">\n <mds-button variant=\"dark\" tone=\"outline\" id=\"btn-no\">Annulla</mds-button>\n <mds-button variant=\"error\" tone=\"strong\" id=\"btn-si\">Elimina</mds-button>\n </div>\n </div>\n</mds-modal>\n\n<script>\n document.getElementById('btn-no').addEventListener('click', () => {\n document.getElementById('conferma-elimina').close();\n });\n</script>\n```\n\n#### Programmatic Close via `close()` Method\n\nCall the async `close()` method from JavaScript when you need to dismiss the modal from outside its UI - for example, after a successful async operation.\n\n```html\n<mds-modal id=\"salvataggio\">\n <div class=\"p-400\">\n <mds-text>Salvataggio in corso...</mds-text>\n </div>\n</mds-modal>\n\n<script>\n async function salva() {\n const modal = document.getElementById('salvataggio');\n modal.opened = true;\n await salvaRisorsa();\n await modal.close();\n }\n</script>\n```\n\n#### Listening to Animation Events\n\n`mdsModalShow` fires when the intro animation completes (the modal is fully visible). Use it to focus the first interactive element. `mdsModalHide` fires when the outro animation completes; use it to detach the element or reset content.\n\n```html\n<mds-modal id=\"modal-focus\" position=\"right\">\n <div class=\"p-400\">\n <mds-input-field label=\"Cerca\">\n <mds-input id=\"input-ricerca\" name=\"ricerca\"></mds-input>\n </mds-input-field>\n </div>\n</mds-modal>\n\n<script>\n const modal = document.getElementById('modal-focus');\n const input = document.getElementById('input-ricerca');\n\n modal.addEventListener('mdsModalShow', () => {\n input.setFocus();\n });\n modal.addEventListener('mdsModalHide', () => {\n // safe point to detach or reset content\n modal.opened = undefined;\n });\n</script>\n```\n\n#### Custom Animation Styles\n\n`animation` selects the motion style. `'slide'` (default) translates from the entry edge; `'3d'` adds a perspective tilt; `'custom'` delegates entirely to the CSS custom properties `--mds-modal-custom-closed-transform` and `--mds-modal-custom-window-distance`.\n\n```html\n<!-- 3D perspective tilt animation -->\n<mds-modal id=\"modal-3d\" animation=\"3d\" position=\"center\">\n <div class=\"p-400\">\n <mds-text>Animazione 3D</mds-text>\n </div>\n</mds-modal>\n\n<!-- Custom animation driven by CSS vars -->\n<mds-modal id=\"modal-custom\" animation=\"custom\" position=\"center\">\n <div class=\"p-400\">\n <mds-text>Animazione personalizzata</mds-text>\n </div>\n</mds-modal>\n```\n\n#### Custom Window via `window` Slot\n\nSlot any element with `slot=\"window\"` to completely replace the built-in chrome (the window surface and the close button). The slotted element gets no `role` of its own: the `<dialog>` the component renders is already the dialog. Use this when a completely bespoke surface is needed - for example, a full-screen banner.\n\n```html\n<mds-modal id=\"modal-banner\" animation=\"custom\">\n <mds-banner\n slot=\"window\"\n class=\"max-w-md w-full mx-400\"\n tone=\"box\"\n deletable\n headline=\"Azione richiesta\"\n >\n <mds-text typography=\"detail\">Conferma la tua identita' per procedere.</mds-text>\n <mds-button slot=\"action\" variant=\"primary\" tone=\"text\">Annulla</mds-button>\n <mds-button slot=\"action\" variant=\"primary\" tone=\"strong\">Conferma</mds-button>\n </mds-banner>\n</mds-modal>\n```\n\n#### Disabling the Backdrop\n\nAdd `hide-backdrop` to render the modal without the dimmed overlay - useful for non-blocking side panels that coexist with interactive page content.\n\n```html\n<mds-modal id=\"pannello-info\" position=\"right\" hide-backdrop>\n <div class=\"p-400\">\n <mds-text>Informazioni contestuali</mds-text>\n </div>\n</mds-modal>\n```\n\n```javascript\n// Remove the backdrop from JavaScript (it applies from the next opening)\ndocument.getElementById('pannello-info').hideBackdrop = true;\n```\n\n#### CSS Customization\n\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(--magma-radius-xl);\n --mds-modal-window-distance: calc(var(--spacing) * 600);\n --mds-modal-window-overflow: hidden;\n --mds-modal-window-background: rgb(var(--magma-surface-overlay));\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(--magma-radius-lg) var(--magma-radius-lg) 0 0;\n --mds-modal-window-max-width: 100%;\n --mds-modal-window-min-width: 100%;\n}\n```\n",
|
|
19506
19701
|
"3. Antipattern": "Common incorrect uses of `<mds-modal>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Set `opened=\"false\"` to Close the Modal\n\nA false boolean is an absent attribute ([`agents/conventions.md`](../../../../agents/conventions.md)). The runtime does parse the string `\"false\"` as `false`, so the modal stays closed, but the attribute is still on the element until the first render, so `[opened]` attribute selectors and any code that reads the attribute see it set. Remove the attribute; from JavaScript set the prop to `undefined` (`false` works too: the component turns it into `undefined`).\n\n```html\n<!-- INCORRECT -->\n<mds-modal id=\"dialogo\" opened=\"false\"></mds-modal>\n\n<!-- CORRECT -->\n<mds-modal id=\"dialogo\"></mds-modal>\n```\n\n#### Do Not Put Content in the `window` Slot Without Replacing the Entire Chrome\n\nThe `window` slot completely bypasses the built-in surface, header/footer regions, and close button. Do not use it to add a header element while expecting the default content area and close button to still render - they will not.\n\n```html\n<!-- INCORRECT: only the slotted header renders; default slot and close button are suppressed -->\n<mds-modal id=\"modal\">\n <header slot=\"window\" class=\"p-400\">Titolo</header>\n <div>Contenuto del dialogo</div>\n</mds-modal>\n\n<!-- CORRECT: use slot=\"top\" for a sticky header, default slot for body -->\n<mds-modal id=\"modal\">\n <header slot=\"top\" class=\"p-400 bg-surface-overlay\">Titolo</header>\n <div class=\"p-400\">Contenuto del dialogo</div>\n</mds-modal>\n```\n\n#### Do Not Reach Into Shadow Parts to Style the Window\n\nThe only supported customization surface is `--mds-modal-*` CSS custom properties and the documented shadow parts (`dialog`, `window`, `action-close`). Targeting internal shadow selectors couples your code to implementation details that will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-modal >>> .window-content {\n padding: 0;\n}\nmds-modal::part(window) > div {\n border: 2px solid red;\n}\n\n/* CORRECT */\nmds-modal {\n --mds-modal-window-background: rgb(var(--magma-surface-overlay));\n --mds-modal-window-radius: var(--magma-radius-xl);\n --mds-modal-window-distance: calc(var(--spacing) * 400);\n}\n```\n\n#### Do Not Listen for Native `click` on the Backdrop to Close\n\n`mds-modal` emits `mdsModalClose` when it closes (and `mdsModalHide` when the animation finishes). Listening for a raw `click` on the host or backdrop is fragile - the event target varies by browser and shadow DOM boundary, and your handler ignores `interaction=\"strict\"`.\n\n```javascript\n// INCORRECT\ndocument.getElementById('modal').addEventListener('click', (e) => {\n if (e.target === e.currentTarget) modal.opened = undefined;\n});\n\n// CORRECT\ndocument.getElementById('modal').addEventListener('mdsModalClose', () => {\n modal.opened = undefined;\n});\n```\n\n#### Do Not Use `<dialog>` Directly When `<mds-modal>` Is Available\n\nUsing a raw `<dialog>` element bypasses the system's managed animation, body-scroll locking, touch-swipe dismissal, and design-token theming. Always use `<mds-modal>` for overlays in a Magma application.\n\n```html\n<!-- INCORRECT -->\n<dialog id=\"raw-dialog\">\n <p>Contenuto del dialogo</p>\n <button>Chiudi</button>\n</dialog>\n\n<!-- CORRECT -->\n<mds-modal id=\"modal\">\n <div class=\"p-400\">\n <mds-text>Contenuto del dialogo</mds-text>\n </div>\n</mds-modal>\n```\n"
|
|
19507
19702
|
},
|
|
@@ -20226,8 +20421,8 @@
|
|
|
20226
20421
|
"filePath": "src/components/mds-notification/mds-notification.tsx",
|
|
20227
20422
|
"encapsulation": "shadow",
|
|
20228
20423
|
"tag": "mds-notification",
|
|
20229
|
-
"readme": "# mds-notification\n\n
|
|
20230
|
-
"docs": "
|
|
20424
|
+
"readme": "# mds-notification\n\n\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
|
|
20425
|
+
"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.",
|
|
20231
20426
|
"docsTags": [],
|
|
20232
20427
|
"usage": {
|
|
20233
20428
|
"1. Description": "The `<mds-notification>` web component is a numeric badge/dot indicator of the Magma Design System that attaches to another element (an icon, a button, an avatar) to signal a count of pending items. It has no HTML primitive equivalent: it positions itself relative to a target element rather than wrapping content of its own.\n\n#### Semantic Behavior\n\n- **Target attachment**: The component anchors to the element matched by the `target` selector and tracks it as it scrolls or resizes.\n- **Missing target falls back**: If `target` is not set, positioning is disabled; if `target` is set but resolves to no element, it logs a console warning (`mds-notification: no valid target found`) and falls back to `strategy=\"disabled\"` as well.\n- **Zero value**: When `value` is `0` the badge renders without a number, as a plain dot; it is not hidden.\n- **Count overflow**: When `max` is set and `value` exceeds it, the displayed text becomes `+max` (e.g. `+9`) instead of the raw number; otherwise the value is locale-formatted.\n- **Accessibility**: The badge carries the current value as its own `aria-label` (the visible number is `aria-hidden`); it does not label the target.\n\n#### Properties & Visual Configurations\n\n- **`target`** is the CSS selector of the element the badge anchors to; it is effectively mandatory for positioned rendering.\n- **`value`** is the count shown in the badge and also the source of the accessible label; `0` shows a plain dot without a number.\n- **`max`** caps the visible number - pick it when raw counts could grow large and you want a compact `+N` ceiling.\n- **`dismissed`** hides the badge independently of its value (the badge is shown by default); it works with the floating strategies (`fixed`, `absolute`) only, with `disabled` the badge stays visible.\n\n#### Other behavioral props\n\n- **`strategy`** selects the positioning mode (`'fixed'` by default, `'absolute'`, or `'disabled'`). Use `'disabled'` to opt out of dynamic tracking; it is also set automatically when no `target` is provided.\n",
|
|
@@ -21061,7 +21256,7 @@
|
|
|
21061
21256
|
}
|
|
21062
21257
|
],
|
|
21063
21258
|
"usage": {
|
|
21064
|
-
"1. Description": "The `<mds-pref>` web component is the accessibility-preferences panel of the Magma Design System: a compound parent that groups user-facing settings (animation, consumption, contrast, theme, language) so people can tune readability, motion, and language for their session. It acts as the coordinator for the `mds-pref-*` children slotted inside it.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-mode`, `mds-pref-theme` and/or `mds-pref-language` children in its default slot; it owns no preference UI of its own beyond coordination (a scheme-constrained `mds-pref-theme` locks the matching `mds-pref-mode` item).\n- **Size propagation**: A change of `size` after load cascades the value down to every nested `mds-pref-*` child; the initial value is not forwarded (the watcher does not run on load), so for the first render set `size` on each child too.\n- **Reload notice**: The panel has an inline caption prompting the user to refresh the page when a preference that cannot apply live (`consumption` or `language`) changes, but it listens for the children's `mdsPrefChange` only in `controller` mode, where the host is hidden: in the visible panel the caption never appears.\n- **Document flag**: While at least one `<mds-pref>` is
|
|
21259
|
+
"1. Description": "The `<mds-pref>` web component is the accessibility-preferences panel of the Magma Design System: a compound parent that groups user-facing settings (animation, consumption, contrast, theme, language) so people can tune readability, motion, and language for their session. It acts as the coordinator for the `mds-pref-*` children slotted inside it.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-mode`, `mds-pref-theme` and/or `mds-pref-language` children in its default slot; it owns no preference UI of its own beyond coordination (a scheme-constrained `mds-pref-theme` locks the matching `mds-pref-mode` item).\n- **Size propagation**: A change of `size` after load cascades the value down to every nested `mds-pref-*` child; the initial value is not forwarded (the watcher does not run on load), so for the first render set `size` on each child too.\n- **Reload notice**: The panel has an inline caption prompting the user to refresh the page when a preference that cannot apply live (`consumption` or `language`) changes, but it listens for the children's `mdsPrefChange` only in `controller` mode, where the host is hidden: in the visible panel the caption never appears.\n- **Document flag**: While at least one `<mds-pref>` is on the page, `<html>` carries `data-magma-pref`, which turns off the styles' fallback to the OS preferences; it is removed only when the last instance leaves the page, so a settings page that unmounts its own panel leaves the app controller in charge. Moving a panel in the DOM (between a sidebar and a menu, or with a client router that keeps it across pages) keeps the flag, the reload notice and the theme lock on the mode control.\n- **Live language sync**: When a `language` change is emitted, the panel re-resolves its own locale so the reload notice is shown in the newly selected language.\n\n#### Properties & Visual Configurations\n\n`size` is one of the shared tab sizes and is forwarded to children rather than styling the host directly - a change on the parent reaches every child, but the initial value does not, so set it on the children as well.\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",
|
|
21065
21260
|
"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 shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Full Preferences Panel\n\nThe canonical form: slot every `mds-pref-*` control directly inside `<mds-pref>`. The parent coordinates the theme and mode controls automatically (a scheme-constrained theme locks the matching mode item) - no extra wiring is needed.\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-theme>\n <mds-pref-theme-item name=\"default\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"cool\"></mds-pref-theme-item>\n </mds-pref-theme>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Partial Panel - Subset of Controls\n\nSlot only the controls your application needs. `<mds-pref>` renders whatever children are present; omitted controls are simply absent.\n\n```html\n<!-- Accessibility-only panel: contrast and animation controls -->\n<mds-pref>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Controlling Size\n\nA later change of the parent's `size` drives all child controls at once, but the initial value is not forwarded (the watcher does not run on load): for the first render set `size` on each child as well.\n\n```html\n<!-- Compact panel for a sidebar or popover -->\n<mds-pref size=\"sm\">\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\n#### Headless Controller Mode\n\nSet the `controller` boolean attribute when you need the preference engine to apply saved preferences from `localStorage` on page load without rendering any visible UI. The host is hidden via CSS (`display: none`) and still activates all child preference controls.\n\n```html\n<!-- Place in <body>; the panel is invisible but activates stored preferences -->\n<mds-pref controller>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Language Selector with Multiple Languages\n\n`<mds-pref-language>` requires its child `<mds-pref-language-item>` elements to be present; the items are not self-generating. Pass language codes supported by your application.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Reload Notice Handling\n\n`<mds-pref>` has an inline caption telling the user to refresh the page after a `consumption` or `language` change, but today it never shows in a visible panel: the parent listens for the children's `mdsPrefChange` only in `controller` mode, where the host is hidden. If your application needs the hint, provide it yourself, and keep in mind that the children emit `mdsPrefChange` on page load too, not only on a user's choice.\n",
|
|
21066
21261
|
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Place Non-Pref Children in the Default Slot\n\nThe default slot accepts only `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-language`, `mds-pref-mode` and `mds-pref-theme` children. Other elements are outside the documented content: they render as extra rows of the panel and take part in no coordination.\n\n```html\n<!-- INCORRECT -->\n<mds-pref>\n <div class=\"custom-section\">Tema</div>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Use `mds-pref-*` Children Outside `<mds-pref>`\n\nEach control applies and stores its own preference, but the coordination between the controls of a panel lives in the parent: a scheme-constrained `mds-pref-theme` item locks the matching `mds-pref-mode` item only inside `<mds-pref>`, and only the parent forwards `size` changes. Group the controls of a panel in `<mds-pref>`.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-mode></mds-pref-mode>\n<mds-pref-theme>\n <mds-pref-theme-item name=\"default\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"cool\"></mds-pref-theme-item>\n</mds-pref-theme>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-theme>\n <mds-pref-theme-item name=\"default\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"cool\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Do Not Set `controller=\"false\"` to Turn Off Controller Mode\n\n`controller` is a boolean attribute, and a false boolean is an absent attribute ([`agents/conventions.md`](../../../../agents/conventions.md)). The runtime parses the string `\"false\"` as `false`, so the panel shows, but the attribute is still on the element until the first render, so `[controller]` attribute selectors (the one that hides the panel included) and any code that reads the attribute see it set. Remove the attribute entirely to switch back to visible mode.\n\n```html\n<!-- INCORRECT -->\n<mds-pref controller=\"false\">\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Listen for the Native `change` Event to Detect Preference Changes\n\nThe controls fire no native `change` event. Use the documented `mdsPrefChange` event emitted by each `mds-pref-*` child; note that a child emits it on page load too, with only the `preference` name in `detail`.\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"
|
|
21067
21262
|
},
|
|
@@ -21133,7 +21328,18 @@
|
|
|
21133
21328
|
],
|
|
21134
21329
|
"methods": [],
|
|
21135
21330
|
"events": [],
|
|
21136
|
-
"listeners": [
|
|
21331
|
+
"listeners": [
|
|
21332
|
+
{
|
|
21333
|
+
"event": "mdsPrefChange",
|
|
21334
|
+
"capture": false,
|
|
21335
|
+
"passive": false
|
|
21336
|
+
},
|
|
21337
|
+
{
|
|
21338
|
+
"event": "mdsPrefThemeChange",
|
|
21339
|
+
"capture": false,
|
|
21340
|
+
"passive": false
|
|
21341
|
+
}
|
|
21342
|
+
],
|
|
21137
21343
|
"styles": [],
|
|
21138
21344
|
"slots": [
|
|
21139
21345
|
{
|
|
@@ -21601,7 +21807,7 @@
|
|
|
21601
21807
|
}
|
|
21602
21808
|
],
|
|
21603
21809
|
"usage": {
|
|
21604
|
-
"1. Description": "The `<mds-pref-language>` web component is the language-preference control of the Magma Design System,
|
|
21810
|
+
"1. Description": "The `<mds-pref-language>` web component is the language-preference control of the Magma Design System, usually slotted inside the [`<mds-pref>`](../mds-pref/AGENTS.md) panel alongside the other preference children. It renders a labelled tab trigger that opens a dropdown of `<mds-pref-language-item>` entries, letting users switch the active document language and persisting that choice.\n\n#### Semantic Behavior\n\n- **Usually inside `<mds-pref>`**: Placed as a direct slot child of `<mds-pref>`, alongside the other `mds-pref-*` controls; it also works on its own, since it applies and stores the language by itself. What it gives up on its own is in the antipattern docs. In turn it hosts its own `<mds-pref-language-item>` children, supplied via its default slot.\n- **Default slot hosts the items**: The default slot accepts one or more `<mds-pref-language-item>` elements; when the control loads, the item whose `code` matches the resolved language is marked selected (a later change of `set` does not move the selection).\n- **Selection orchestration**: Selecting an item clears the others, closes the dropdown, and resolves the new language - the children report up to this component, which centralizes the single-selection state.\n- **Language resolution & persistence**: When `set` is `auto` the active language is resolved in priority order from the persisted value, then the `<html lang>` attribute, then `navigator.language`. The resolved value is persisted and written to `<html lang>` - the single page-wide source of truth for the language. Every localized Magma component (including ones nested in shadow DOM) reacts automatically through a shared reactive store; there is no per-element `lang` override and no imperative refresh method. Applications that manage the language themselves can simply set `<html lang>`: the store observes it.\n- **Events bubbled to the parent**: Emits `mdsPrefLanguageChange` on every item pick, also when the picked language is already active (detail carries the selected `language` code; it fires just before the language is applied), and `mdsPrefChange` (detail `{ preference: 'language' }`), fired only when the resolved language actually changes, from a pick or from a new `set` value (the initial application on load does not emit). The latter is the event `<mds-pref>` listens to for its \"reload required\" notice, since application-level content may still need a reload.\n- **Invalid codes 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`). The parent `<mds-pref>` forwards its own `size` to every `mds-pref-*` child only when that prop changes after load, not from the initial markup: to size the control from markup, set `size` here.\n",
|
|
21605
21811
|
"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 shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Language Selector Inside `mds-pref`\n\nThe canonical usage. Nest `<mds-pref-language>` as a direct child of [`<mds-pref>`](../mds-pref/AGENTS.md) and populate its default slot with one [`<mds-pref-language-item>`](../mds-pref-language-item/AGENTS.md) per supported locale. The `code` attribute on each item must be a valid BCP 47 short tag.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Forcing a Starting Language with `set`\n\nPass an explicit BCP 47 tag to `set` to override the automatic resolution chain. Use this when the application dictates an initial language regardless of the user's browser setting or persisted preference.\n\n```html\n<mds-pref>\n <mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Automatic Language Resolution (default)\n\nOmit `set` (or pass `set=\"auto\"`) to let the component resolve the active language in priority order: persisted user choice, then the page `<html lang>` attribute, then `navigator.language`. This is the right choice for most applications.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Sizing via `size`\n\nUse the `size` prop to size the tab trigger. The parent [`<mds-pref>`](../mds-pref/AGENTS.md) forwards its own `size` to every `mds-pref-*` child only when that prop changes after load, not from the initial markup: in markup, set `size` on each preference control, with the same value to keep the group consistent.\n\n```html\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 language (for example, to reload the page or re-fetch translated content). The event detail carries the selected `language` code string. It fires on every pick, also when the picked language is already the active one.\n\n```html\n<mds-pref>\n <mds-pref-language id=\"lang-selector\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n\n<script>\n document.querySelector('#lang-selector').addEventListener('mdsPrefLanguageChange', (e) => {\n console.log('Nuova lingua selezionata:', e.detail.language);\n // e.g. reload the page to apply the new locale\n window.location.reload();\n });\n</script>\n```\n\n#### Full Preference Panel with Language\n\n`<mds-pref-language>` is one of several preference children accepted by [`<mds-pref>`](../mds-pref/AGENTS.md). Compose it alongside the other controls to offer a complete preferences UI.\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n",
|
|
21606
21812
|
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Use Outside `mds-pref`\n\n`<mds-pref-language>` is a compound child designed to live inside [`<mds-pref>`](../mds-pref/AGENTS.md). As a standalone widget it still applies and persists the language, but it leaves the preference group: `<mds-pref>` forwards `size` changes to its `mds-pref-*` children and listens to their `mdsPrefChange` for the reload-required notice.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n</mds-pref-language>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Do Not Slot Arbitrary HTML Instead of `mds-pref-language-item`\n\nThe default slot accepts only `<mds-pref-language-item>` elements. Slotting raw `<button>`, `<li>`, or other elements bypasses the selection orchestration and event wiring the parent depends on.\n\n```html\n<!-- INCORRECT -->\n<mds-pref>\n <mds-pref-language>\n <button>Italiano</button>\n <button>English</button>\n </mds-pref-language>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Do Not Pass an Unrecognized Language Code to `set`\n\nThe `set` prop must be either `\"auto\"` or a 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: when it loads it marks only the item whose `code` matches, and on each pick it clears the siblings. A `selected` written in the markup is overwritten on load; one set later from script leaves the visual selection out of step with the active language.\n\n```html\n<!-- INCORRECT -->\n<mds-pref>\n <mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\" selected></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n\n<!-- CORRECT - the parent derives selection from `set` -->\n<mds-pref>\n <mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Do Not Listen to `mdsPrefLanguageItemSelect` Instead of `mdsPrefLanguageChange`\n\n`mdsPrefLanguageItemSelect` is the item's own event, emitted by `<mds-pref-language-item>` and consumed by its parent. Application code should listen to `mdsPrefLanguageChange` on `<mds-pref-language>`: one listener for the whole list, fired after the parent has committed the selection (the language is applied right after it, so read it from `e.detail.language`).\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelector('mds-pref-language-item').addEventListener('mdsPrefLanguageItemSelect', (e) => {\n console.log(e.detail.language);\n });\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-pref-language').addEventListener('mdsPrefLanguageChange', (e) => {\n console.log(e.detail.language);\n });\n</script>\n```\n\n#### Do Not Set Size via CSS Instead of the `size` Prop\n\nThe `size` prop is the only supported way to resize the internal tab trigger. Overriding dimensions with inline styles or CSS custom properties not listed in the component's documented surface couples your code to internal implementation details.\n\n```css\n/* INCORRECT */\nmds-pref-language mds-tab-item {\n font-size: 10px;\n}\n```\n\n```html\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-language size=\"sm\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n"
|
|
21607
21813
|
},
|
|
@@ -21874,7 +22080,7 @@
|
|
|
21874
22080
|
"docs": "",
|
|
21875
22081
|
"docsTags": [],
|
|
21876
22082
|
"usage": {
|
|
21877
|
-
"1. Description": "The `<mds-pref-mode>` web component is the mode preference control of the Magma Design System,
|
|
22083
|
+
"1. Description": "The `<mds-pref-mode>` web component is the mode preference control of the Magma Design System, usually a direct child of the [`<mds-pref>`](../mds-pref/AGENTS.md) panel. It renders a labelled three-way tab (light / system / dark) that lets the user pick a color-scheme mode and applies it globally to the document.\n\n#### Semantic Behavior\n\n- **Usually inside `<mds-pref>`**: Placed as a direct slot child of `<mds-pref>`, alongside the other `mds-pref-*` controls; it also works on its own, since it applies and stores the mode by itself. What it gives up on its own is in the antipattern docs.\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' }` every time the mode is applied: on load and on each pick, so one pick can emit it more than once. It bubbles up to `<mds-pref>`; a mode change needs no reload, so it raises no reload notice.\n- **Instances stay in sync**: Instances mounted together (a hidden `<mds-pref controller>` and a visible settings panel) share the applied mode: a pick in one is mirrored by the others, which neither apply it again nor emit `mdsPrefChange`. A `pref-mode-*` class written on `<html>` by other code is mirrored the same way.\n- **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`). The parent `<mds-pref>` forwards its own `size` to every `mds-pref-*` child only when that prop changes after load, not from the initial markup: in markup, set it here (with the same value on the sibling preferences, so the group stays visually consistent).\n",
|
|
21878
22084
|
"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 [`agents/theming.md`](../../../../agents/theming.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Default Usage Inside `mds-pref`\n\nThe canonical form. Slot `<mds-pref-mode>` as a direct child of [`<mds-pref>`](../mds-pref/AGENTS.md) with no extra props. The component restores the user's previously persisted mode automatically on load.\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Setting an Initial Mode\n\nPass `mode` to force the selector to start on a specific mode rather than reading from `localStorage`. Useful when the host application controls preference state centrally. The forced mode is also written to `localStorage` on every load, replacing the user's last choice.\n\n```html\n<mds-pref>\n <mds-pref-mode mode=\"dark\"></mds-pref-mode>\n</mds-pref>\n```\n\n#### Using `system` Mode for OS-Aware Default\n\n`mode=\"system\"` resolves to light or dark based on the OS `prefers-color-scheme` media query. Use this as the explicit starting point when you want the app to follow the OS without the user having to choose.\n\n```html\n<mds-pref>\n <mds-pref-mode mode=\"system\"></mds-pref-mode>\n</mds-pref>\n```\n\n#### Choosing a Transition Style\n\n`transition` controls the visual effect when switching between schemes. Use `smooth` (default) for a mid-fade overlay that hides the color flip, `flash` for an instant switch with a brief full-screen pulse, or `none` for a hard switch with no animation.\n\n```html\n<!-- Smooth fade (default) -->\n<mds-pref-mode transition=\"smooth\"></mds-pref-mode>\n\n<!-- Instant flash pulse -->\n<mds-pref-mode transition=\"flash\"></mds-pref-mode>\n\n<!-- No animation -->\n<mds-pref-mode transition=\"none\"></mds-pref-mode>\n```\n\n#### Listening for Mode Changes\n\nThe component emits `mdsPrefChange` with `{ preference: 'mode' }` each time the mode is applied, on load and on each pick, so expect repeats with the same mode; another instance that mirrors the pick does not emit it. Listen for this event to react in application code - for example to sync a preference state store - and read the current value from the `mode` prop.\n\n```html\n<mds-pref>\n <mds-pref-mode id=\"mode-selector\"></mds-pref-mode>\n</mds-pref>\n\n<script>\n document.getElementById('mode-selector').addEventListener('mdsPrefChange', (e) => {\n console.log('Modalita tema cambiata:', e.detail.preference);\n });\n</script>\n```\n\n#### Controlling Size via the Parent\n\n`size` is forwarded to the internal tab items. [`<mds-pref>`](../mds-pref/AGENTS.md) forwards its own `size` to every `mds-pref-*` child only when that prop changes after load, not from the initial markup: in markup, set the same `size` on every preference control to keep the panel at one tab size.\n\n```html\n<mds-pref>\n <mds-pref-mode size=\"sm\"></mds-pref-mode>\n <mds-pref-contrast size=\"sm\"></mds-pref-contrast>\n</mds-pref>\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",
|
|
21879
22085
|
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-pref-mode>` Outside `<mds-pref>`\n\n`<mds-pref-mode>` is a compound child: `<mds-pref>` forwards `size` changes to it and locks the mode item that a scheme-constrained `<mds-pref-theme>` forbids (it sets `lockedScheme`). As a standalone widget it still applies and persists the mode, but nothing coordinates it with the theme.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-mode></mds-pref-mode>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Set `transition=\"false\"` to Disable the Overlay\n\n`transition` is a string enum, not a boolean. `\"false\"` is not a valid value: it only happens to fall through to the no-overlay branch, with no guarantee across releases. Use `transition=\"none\"` to opt out of the overlay animation.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-mode transition=\"false\"></mds-pref-mode>\n\n<!-- CORRECT -->\n<mds-pref-mode transition=\"none\"></mds-pref-mode>\n```\n\n#### Do Not Listen for Native `change` Events Instead of `mdsPrefChange`\n\nThe component does not emit or bubble native `change` events out of the shadow DOM. Always listen for the documented `mdsPrefChange` custom event.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelector('mds-pref-mode').addEventListener('change', handler);\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-pref-mode').addEventListener('mdsPrefChange', handler);\n</script>\n```\n\n#### Do Not Override Mode Classes on `<html>` Directly\n\nThe component manages `pref-mode-light`, `pref-mode-dark`, and `pref-mode-system` classes on `<html>` itself. Adding or removing these by hand races with the component and will be overwritten on the next mode change. Drive the mode exclusively through the `mode` prop.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.documentElement.classList.add('pref-mode-dark');\n</script>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode mode=\"dark\"></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Size Only One Child of the Panel\n\n`<mds-pref>` forwards its own `size` to its preference children only when that prop changes after load, not from the initial markup, so in markup each child carries its own `size`. Setting it on `<mds-pref-mode>` alone 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>\n <mds-pref-mode size=\"sm\"></mds-pref-mode>\n <mds-pref-contrast size=\"sm\"></mds-pref-contrast>\n</mds-pref>\n```\n\n#### Do Not Target the Injected Overlay to Customize It\n\nThe overlay element is injected into `document.body` at runtime with inline styles, which win over a class selector anyway. Do not target it by class name or adjust its properties through JavaScript. Use the 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"
|
|
21880
22086
|
},
|
|
@@ -22111,7 +22317,7 @@
|
|
|
22111
22317
|
}
|
|
22112
22318
|
],
|
|
22113
22319
|
"usage": {
|
|
22114
|
-
"1. Description": "The `<mds-pref-theme>` web component is the theme-switcher segment of the Magma accessibility preferences panel,
|
|
22320
|
+
"1. Description": "The `<mds-pref-theme>` web component is the theme-switcher segment of the Magma accessibility preferences panel, usually a direct child of [`<mds-pref>`](../mds-pref/AGENTS.md). It renders a labelled tab trigger that opens a dropdown of selectable named themes and, when a theme is chosen, applies it globally to the document.\n\n#### Semantic Behavior\n\n- **Usually inside `<mds-pref>`**: Placed as a direct slot child of `<mds-pref>`, alongside the other `mds-pref-*` controls; it also works on its own, since it applies and stores the theme by itself. What it gives up on its own is in the antipattern docs.\n- **Acts as a sub-parent itself**: Its own default slot must contain one or more `mds-pref-theme-item` elements; it drives their selected state so only the active theme is marked selected.\n- **Global theme application**: Selecting an item applies the theme document-wide: it writes `data-theme-name` and the `pref-theme-scheme-*` class on `<html>`.\n- **Persistence and hydration**: The current name, scheme and corner shape are persisted and restored across reloads: a stored value outranks the matching prop.\n- **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 each pick, which `<mds-pref>` listens to in order to lock the `<mds-pref-mode>` item a scheme-constrained theme forbids. It also emits `mdsPrefChange` (`preference: 'theme'`, and `'corner-shape'` when a corner shape is set) every time it applies them, on load and on each re-render included.\n- **Localized label**: The \"Theme\" heading follows the active interface language.\n- **Trigger text**: The closed control shows the `label` of the item for the active theme, the same text the open list shows (localize the items, the trigger follows); when no item matches the active theme it shows the label derived from the name (`dark-blue` -> \"Dark blue\").\n\n#### Properties & Visual Configurations\n\n- **`name`**: The active theme name (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. The named themes are `cool` and `warm`; `default` is the base theme ([`agents/theming.md`](../../../../agents/theming.md)).\n- **`scheme`**: Constrains the colour modes of the theme to `'light'`, `'dark'`, or `'all'` (default). Pick `'all'` for themes that ship both light and dark palettes; pick `'light'` or `'dark'` to force a single mode for a theme offered in one mode only.\n- **`size`**: Sets the size (`'sm'` / `'md'`) of the nested tab UI. `<mds-pref>` forwards its own `size` to every `mds-pref-*` segment only when that prop changes after load, not from the initial markup: in markup, set it here (with the same value on the sibling segments, so the panel stays visually consistent).\n- **`cornerShape`** (attribute `corner-shape`): The corner geometry of the whole page - `round`, `squircle`, `bevel`, `notch`, `scoop`, `square`, or `default`. It writes `data-corner-shape` on `<html>` and is persisted like the theme; `default` removes the attribute, and leaving the prop unset touches nothing ([`agents/theming.md`](../../../../agents/theming.md)).\n",
|
|
22115
22321
|
"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 [`agents/theming.md`](../../../../agents/theming.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Theme Chooser\n\nThe canonical form. Place `<mds-pref-theme>` inside [`<mds-pref>`](../mds-pref/AGENTS.md) and populate its default slot with one [`<mds-pref-theme-item>`](../mds-pref-theme-item/AGENTS.md) per available theme. The item whose `name` matches the active theme (the stored choice, or the parent's `name` on a first visit) starts as selected. The named themes are `cool` and `warm`; `default` is the base theme.\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=\"Freddo\" name=\"cool\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Caldo\" name=\"warm\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Scheme-Constrained Themes\n\nUse `scheme=\"light\"` or `scheme=\"dark\"` on a `<mds-pref-theme-item>` when the theme must be offered in one colour mode only. The parent component propagates the chosen scheme to `<html>` and forces that mode even if the user's OS or mode preference asks for the opposite; inside `<mds-pref>` the forbidden item of `<mds-pref-mode>` is locked.\n\n```html\n<mds-pref>\n <mds-pref-theme name=\"default\" scheme=\"all\">\n <mds-pref-theme-item label=\"Predefinito\" name=\"default\" scheme=\"all\"></mds-pref-theme-item>\n <!-- light only - dark mode will not activate with this item -->\n <mds-pref-theme-item label=\"Freddo chiaro\" name=\"cool\" scheme=\"light\"></mds-pref-theme-item>\n <!-- dark only -->\n <mds-pref-theme-item label=\"Caldo scuro\" name=\"warm\" 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=\"Freddo\" name=\"cool\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n\n<script>\n document.querySelector('#theme-chooser').addEventListener('mdsPrefThemeChange', (e) => {\n console.log('Tema attivo:', e.detail.name, '- Schema:', e.detail.scheme);\n });\n</script>\n```\n\n#### Declaring the Initial Theme\n\nUse the `name` prop to declare which theme should be active before the user makes a selection. If `localStorage` already holds a persisted value it takes precedence; otherwise the component applies `name` on first render.\n\n```html\n<mds-pref>\n <!-- First-visit default is \"warm\" -->\n <mds-pref-theme name=\"warm\" scheme=\"all\">\n <mds-pref-theme-item label=\"Predefinito\" name=\"default\" scheme=\"all\"></mds-pref-theme-item>\n <mds-pref-theme-item label=\"Caldo\" name=\"warm\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Controlling Item Size\n\nPass `size=\"sm\"` when the preferences panel must fit a compact layout. `<mds-pref>` forwards its own `size` to every `mds-pref-*` child only when that prop changes after load, not from the initial markup: in markup, set the same `size` on every preference control.\n\n```html\n<mds-pref>\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=\"Freddo\" name=\"cool\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Styling Theme Items\n\nStyle theme items only through their documented `--mds-pref-theme-item-*` CSS custom properties. Set them on the item host or on a parent selector; name a semantic role, `rgb(var(--magma-<role>))` ([`agents/color.md`](../../../../agents/color.md)), so the colours follow the mode, the theme and the contrast preference.\n\n```css\nmds-pref-theme-item {\n --mds-pref-theme-item-color-background: rgb(var(--magma-surface-inverse));\n --mds-pref-theme-item-color-variant-primary: rgb(var(--magma-accent-emphasis));\n}\n```\n",
|
|
22116
22322
|
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Use the Component Outside `<mds-pref>`\n\n`<mds-pref-theme>` is a compound sub-part designed to slot inside [`<mds-pref>`](../mds-pref/AGENTS.md). As a standalone widget it still applies and persists the theme, but it leaves the panel: `<mds-pref>` can no longer forward `size` changes to it, nor lock the `<mds-pref-mode>` item that its `scheme` forbids.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-theme name=\"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=\"Freddo\" name=\"cool\" scheme=\"all\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Do Not Use an Invalid Theme Name\n\nThe `name` prop must match the pattern `^[a-z]+(-[a-z]+)*$` (lowercase letters and hyphens only). Any other value - including uppercase, underscores, or spaces - 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=\"warm\" scheme=\"all\">...</mds-pref-theme>\n```\n\n#### Do Not Listen for the Native `change` Event\n\n`<mds-pref-theme>` emits `mdsPrefThemeChange` - a documented custom event with a typed `{ name, scheme }` detail. Listening for the native `change` event will not fire because theme selection is handled entirely inside shadow DOM.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelector('mds-pref-theme').addEventListener('change', (e) => {\n console.log(e.target.value); // undefined - wrong event, wrong detail shape\n });\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-pref-theme').addEventListener('mdsPrefThemeChange', (e) => {\n console.log(e.detail.name, e.detail.scheme);\n });\n</script>\n```\n\n#### Do Not Give the Parent and the Child Different Sizes\n\n`<mds-pref>` forwards its own `size` to all `mds-pref-*` children only when that prop changes after load, not from the initial markup, and then it overwrites theirs. A `size` on `<mds-pref-theme>` that differs from the parent's renders the child's value at load and flips to the parent's on its next change: give the children one `size`.\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>\n <mds-pref-theme size=\"sm\" 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"
|
|
22117
22323
|
},
|
|
@@ -24591,7 +24797,7 @@
|
|
|
24591
24797
|
}
|
|
24592
24798
|
],
|
|
24593
24799
|
"usage": {
|
|
24594
|
-
"1. Description": "The `<mds-radial-menu>` web component is a floating action menu of the Magma Design System that arranges its child items along a circular arc around a central trigger button, expanding them outward when opened. It is the parent of a compound pair: it owns the trigger and the geometry, while each option is supplied as an `<mds-radial-menu-item>` in the `item` slot.\n\n#### Semantic Behavior\n\n- **Trigger button**: Renders a trigger button whose `tone`, `variant` and `size` are forwarded from the host; clicking it toggles the menu open and closed.\n- **Open state**: `opened` is the source of truth for visibility; when set the items animate out along the arc and the trigger icon swaps to a close glyph.\n- **Interaction mode**: With `interaction=\"rightclick\"` the trigger is hidden and the menu instead opens on right-click, centred on the cursor.\n- **Backdrop**: When `backdrop` is enabled a dimming overlay is shown while the menu is open. It is purely visual: it lets clicks through and does not close the menu.\n- **Item registration**: Items are read from the `item` slot; the component assigns each item's position and propagates the host `size` down to every `<mds-radial-menu-item>`.\n\n#### Properties & Visual Configurations\n\nThe internal trigger consumes the shared `variant` / `tone` / `size` ladders defined in [`agents/variants.md`](../../../../agents/variants.md); they default to `'dark'` / `'strong'` / `'lg'` here.\n\n#### Other behavioral props\n\n- **`angleStart`** and **`angleEnd`** define the angular sweep (in degrees) over which items are distributed; a 360-degree span produces a full ring, while a narrower range produces a fan. Setting `angleStart` greater than `angleEnd` reverses the distribution.\n- **`radius`** sets the distance (in `rem`) of the items from the centre, controlling how far they travel when the menu opens.\n- **`direction`** chooses whether items lay out `'clockwise'` or `'counterclockwise'` around the arc.\n- **`interaction`** selects how the menu is summoned: `'click'` shows the trigger button, `'rightclick'` hides it and opens at the cursor.\n- **`disc`** renders a decorative disc beneath the menu; **`icon`** overrides the default trigger glyph and defaults to the \"more-vert\" Material icon when unset.\n",
|
|
24800
|
+
"1. Description": "The `<mds-radial-menu>` web component is a floating action menu of the Magma Design System that arranges its child items along a circular arc around a central trigger button, expanding them outward when opened. It is the parent of a compound pair: it owns the trigger and the geometry, while each option is supplied as an `<mds-radial-menu-item>` in the `item` slot.\n\n#### Semantic Behavior\n\n- **Trigger button**: Renders a trigger button whose `tone`, `variant` and `size` are forwarded from the host; clicking it toggles the menu open and closed. It is icon-only and named in the page language (the `lang` of `<html>`) after what a click does: \"Open menu\", then \"Close menu\". There is no prop to give it a name of your own yet.\n- **Open state**: `opened` is the source of truth for visibility; when set the items animate out along the arc and the trigger icon swaps to a close glyph.\n- **Interaction mode**: With `interaction=\"rightclick\"` the trigger is hidden and the menu instead opens on right-click, centred on the cursor.\n- **Backdrop**: When `backdrop` is enabled a dimming overlay is shown while the menu is open. It is purely visual: it lets clicks through and does not close the menu.\n- **Item registration**: Items are read from the `item` slot; the component assigns each item's position and propagates the host `size` down to every `<mds-radial-menu-item>`.\n\n#### Properties & Visual Configurations\n\nThe internal trigger consumes the shared `variant` / `tone` / `size` ladders defined in [`agents/variants.md`](../../../../agents/variants.md); they default to `'dark'` / `'strong'` / `'lg'` here.\n\n#### Other behavioral props\n\n- **`angleStart`** and **`angleEnd`** define the angular sweep (in degrees) over which items are distributed; a 360-degree span produces a full ring, while a narrower range produces a fan. Setting `angleStart` greater than `angleEnd` reverses the distribution.\n- **`radius`** sets the distance (in `rem`) of the items from the centre, controlling how far they travel when the menu opens.\n- **`direction`** chooses whether items lay out `'clockwise'` or `'counterclockwise'` around the arc.\n- **`interaction`** selects how the menu is summoned: `'click'` shows the trigger button, `'rightclick'` hides it and opens at the cursor.\n- **`disc`** renders a decorative disc beneath the menu; **`icon`** overrides the default trigger glyph and defaults to the \"more-vert\" Material icon when unset.\n",
|
|
24595
24801
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-radial-menu>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n`<mds-radial-menu>` is a compound component: it always needs one or more [`mds-radial-menu-item`](../mds-radial-menu-item/AGENTS.md) children placed in the `item` slot.\n\n#### Basic Radial Menu\n\nThe minimal form: a trigger button with items arranged in a full ring. Each item requires `icon` (a slug from the Magma icon library) and `tooltip` (the accessible label shown on hover). The parent propagates its `size` down to every item automatically.\n\n```html\n<mds-radial-menu>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/favorite\" tooltip=\"Aggiungi ai preferiti\" variant=\"dark\" tone=\"weak\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/email\" tooltip=\"Invia email\" variant=\"dark\" tone=\"weak\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/print\" tooltip=\"Stampa\" variant=\"dark\" tone=\"weak\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/delete\" tooltip=\"Elimina\" variant=\"error\"></mds-radial-menu-item>\n</mds-radial-menu>\n```\n\n#### Trigger Button Variant and Tone\n\nUse `variant` and `tone` to style the central trigger button to match the surrounding UI. Defaults are `variant=\"dark\"` and `tone=\"strong\"`.\n\n```html\n<!-- Primary trigger in a content area -->\n<mds-radial-menu variant=\"primary\" tone=\"strong\">\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/edit\" tooltip=\"Modifica\" variant=\"primary\" tone=\"weak\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/ios-share\" tooltip=\"Condividi\" variant=\"primary\" tone=\"weak\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/delete\" tooltip=\"Elimina\" variant=\"error\" tone=\"weak\"></mds-radial-menu-item>\n</mds-radial-menu>\n\n<!-- Light trigger: painted in the paper of the mode (white in light mode, black in dark mode) -->\n<mds-radial-menu variant=\"light\" tone=\"weak\">\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/favorite\" tooltip=\"Aggiungi ai preferiti\" variant=\"light\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/ios-share\" tooltip=\"Condividi\" variant=\"light\"></mds-radial-menu-item>\n</mds-radial-menu>\n```\n\n#### Fan Layout with Angle Range\n\nRestrict `angle-start` and `angle-end` to create a fan instead of a full ring. This is useful when the component is positioned in a corner of a card or image where a full ring would overlap content.\n\n```html\n<!-- Quarter-circle fan opening toward the top-left, placed at the bottom-right corner -->\n<mds-radial-menu angle-start=\"180\" angle-end=\"270\" direction=\"counterclockwise\" radius=\"5\">\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/favorite\" tooltip=\"Aggiungi ai preferiti\" variant=\"light\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/ios-share\" tooltip=\"Condividi\" variant=\"light\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/delete\" tooltip=\"Elimina\" variant=\"error\"></mds-radial-menu-item>\n</mds-radial-menu>\n```\n\n#### Adjusting the Radius\n\nSet `radius` (in `rem`) to control how far items travel from the trigger when the menu opens. Increase it when items would otherwise overlap; decrease it in constrained layouts.\n\n```html\n<mds-radial-menu radius=\"7\" variant=\"primary\" tone=\"outline\">\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/edit\" tooltip=\"Modifica\" variant=\"primary\" tone=\"weak\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/content-copy\" tooltip=\"Copia\" variant=\"primary\" tone=\"weak\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/delete\" tooltip=\"Elimina\" variant=\"error\" tone=\"weak\"></mds-radial-menu-item>\n</mds-radial-menu>\n```\n\n#### Controlling the Open State Programmatically\n\nThe `opened` attribute reflects the menu's open state and can be set from JavaScript to open or close the menu without a user interaction. Remove the attribute (or set the prop to `undefined`; `false` is normalized to `undefined` too) to close it - do not write `opened=\"false\"` in markup.\n\n```html\n<mds-radial-menu id=\"menu-azioni\">\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/edit\" tooltip=\"Modifica\" variant=\"dark\" tone=\"weak\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/delete\" tooltip=\"Elimina\" variant=\"error\" tone=\"weak\"></mds-radial-menu-item>\n</mds-radial-menu>\n\n<script>\n const menu = document.querySelector('#menu-azioni');\n // open programmatically\n menu.opened = true;\n // close programmatically\n menu.opened = undefined;\n</script>\n```\n\n#### Contextual (Right-Click) Menu with Backdrop\n\nSet `interaction=\"rightclick\"` to hide the trigger button and open the menu at the cursor position on a context-menu event. Add `backdrop` to dim the page while the menu is open (the overlay is visual only: it does not block clicks).\n\n```html\n<mds-radial-menu interaction=\"rightclick\" disc backdrop>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/favorite\" tooltip=\"Aggiungi ai preferiti\" variant=\"dark\" tone=\"text\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/email\" tooltip=\"Invia email\" variant=\"dark\" tone=\"text\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/insert-drive-file\" tooltip=\"Nuovo documento\" variant=\"dark\" tone=\"text\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/info\" tooltip=\"Informazioni\" variant=\"dark\" tone=\"text\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/print\" tooltip=\"Stampa\" variant=\"dark\" tone=\"text\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/delete\" tooltip=\"Elimina\" variant=\"error\" tone=\"text\"></mds-radial-menu-item>\n</mds-radial-menu>\n```\n\n#### Disc Decoration\n\nEnable the `disc` attribute to render a decorative circular background beneath the items, visually grouping the open menu. Combine with `backdrop` for modal-style emphasis.\n\n```html\n<mds-radial-menu disc variant=\"dark\" tone=\"strong\">\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/edit\" tooltip=\"Modifica\" variant=\"dark\" tone=\"weak\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/ios-share\" tooltip=\"Condividi\" variant=\"dark\" tone=\"weak\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/delete\" tooltip=\"Elimina\" variant=\"error\" tone=\"weak\"></mds-radial-menu-item>\n</mds-radial-menu>\n```\n\n#### Custom Trigger Icon\n\nOverride the default \"more-vert\" glyph with any slug from the Magma icon library using the `icon` prop. The trigger automatically switches to the close icon while the menu is open.\n\n```html\n<mds-radial-menu icon=\"mi/baseline/add\" variant=\"primary\" tone=\"strong\">\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/edit\" tooltip=\"Modifica\" variant=\"primary\" tone=\"weak\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/content-copy\" tooltip=\"Duplica\" variant=\"primary\" tone=\"weak\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/delete\" tooltip=\"Elimina\" variant=\"error\" tone=\"weak\"></mds-radial-menu-item>\n</mds-radial-menu>\n```\n\n#### Sizing\n\nUse the `size` prop to resize the trigger button and all items simultaneously. Do not override dimensions with inline `width` / `height`.\n\n```html\n<mds-radial-menu size=\"sm\" variant=\"dark\" tone=\"strong\">\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/edit\" tooltip=\"Modifica\" variant=\"dark\" tone=\"weak\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/delete\" tooltip=\"Elimina\" variant=\"error\" tone=\"weak\"></mds-radial-menu-item>\n</mds-radial-menu>\n```\n\n#### Styling Customization\n\nStyle the component through its documented `--mds-radial-menu-*` CSS custom properties. Use semantic color roles wrapped in `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working. Set the radius and the angles with the `radius`, `angle-start` and `angle-end` props: the component writes `--mds-radial-menu-radius`, `--mds-radial-menu-angle-start` and `--mds-radial-menu-angle-end` inline on the host, so a stylesheet cannot override them.\n\n```css\n.my-context mds-radial-menu {\n --mds-radial-menu-transition-duration: 300ms;\n --mds-radial-menu-disc-background: rgb(var(--magma-surface-overlay) / 0.8);\n --mds-radial-menu-disc-size: 12rem;\n}\n```\n",
|
|
24596
24802
|
"3. Antipattern": "Common incorrect uses of `<mds-radial-menu>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Close the Menu by Setting `opened=\"false\"`\n\n`opened` is a boolean prop. Stencil reads `\"false\"` as `false` and, since `opened` is reflected, removes the attribute at the first render, so this happens to work; but the markup says the opposite of what it does, and on a prop that is not reflected the attribute stays in the DOM, where `[attr]` selectors still match it. Remove the attribute or set the prop to `undefined` to close the menu.\n\n```html\n<!-- INCORRECT -->\n<mds-radial-menu opened=\"false\">...</mds-radial-menu>\n\n<!-- CORRECT -->\n<mds-radial-menu>...</mds-radial-menu>\n```\n\n#### Do Not Place Non-Item Children in the `item` Slot\n\nOnly `<mds-radial-menu-item>` elements belong in the `item` slot. Slotting arbitrary HTML or other components breaks the positioning and size-propagation logic.\n\n```html\n<!-- INCORRECT -->\n<mds-radial-menu>\n <mds-button slot=\"item\" label=\"Azione\" variant=\"primary\"></mds-button>\n <button slot=\"item\">Azione</button>\n</mds-radial-menu>\n\n<!-- CORRECT -->\n<mds-radial-menu>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/edit\" tooltip=\"Azione\" variant=\"primary\" tone=\"weak\"></mds-radial-menu-item>\n</mds-radial-menu>\n```\n\n#### Do Not Set Item Size Individually\n\n`<mds-radial-menu>` propagates its `size` prop down to every `<mds-radial-menu-item>` automatically. Setting `size` on individual items is overridden on the next update and produces inconsistent results.\n\n```html\n<!-- INCORRECT -->\n<mds-radial-menu size=\"lg\">\n <mds-radial-menu-item slot=\"item\" size=\"sm\" icon=\"mi/baseline/edit\" tooltip=\"Modifica\" variant=\"dark\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" size=\"xl\" icon=\"mi/baseline/delete\" tooltip=\"Elimina\" variant=\"error\"></mds-radial-menu-item>\n</mds-radial-menu>\n\n<!-- CORRECT -->\n<mds-radial-menu size=\"lg\">\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/edit\" tooltip=\"Modifica\" variant=\"dark\"></mds-radial-menu-item>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/delete\" tooltip=\"Elimina\" variant=\"error\"></mds-radial-menu-item>\n</mds-radial-menu>\n```\n\n#### Do Not Listen for Native `contextmenu` to Drive `interaction=\"rightclick\"`\n\nWhen `interaction=\"rightclick\"` the component registers its own `contextmenu` listener on `document` and prevents the default browser menu. Adding a second listener from application code causes both to fire and may reopen the menu after it closes.\n\n```js\n// INCORRECT\ndocument.addEventListener('contextmenu', (e) => {\n e.preventDefault();\n menu.opened = true; // fights the component's own handler\n});\n\n// CORRECT - just set the prop and let the component manage it\nmenu.interaction = 'rightclick';\n```\n\n#### Do Not Override Geometry via Inline Styles\n\nThe arc geometry is driven by `angle-start`, `angle-end`, `radius`, and `direction` props - not by inline CSS. Applying `transform`, `top`, or `left` directly on the host or items conflicts with the component's own animation values.\n\n```html\n<!-- INCORRECT -->\n<mds-radial-menu style=\"transform: rotate(45deg);\">\n <mds-radial-menu-item slot=\"item\" style=\"transform: translateX(80px);\" icon=\"mi/baseline/edit\" tooltip=\"Modifica\" variant=\"dark\"></mds-radial-menu-item>\n</mds-radial-menu>\n\n<!-- CORRECT -->\n<mds-radial-menu angle-start=\"45\" angle-end=\"315\" radius=\"6\" direction=\"clockwise\">\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/edit\" tooltip=\"Modifica\" variant=\"dark\"></mds-radial-menu-item>\n</mds-radial-menu>\n```\n\n#### Do Not Use an Item Without a `tooltip`\n\n`<mds-radial-menu-item>` renders icon-only buttons. Without a `tooltip` there is no visible label and the accessible name falls back to the icon name (`delete`), which names the icon, not the item's purpose.\n\n```html\n<!-- INCORRECT -->\n<mds-radial-menu>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/delete\" variant=\"error\"></mds-radial-menu-item>\n</mds-radial-menu>\n\n<!-- CORRECT -->\n<mds-radial-menu>\n <mds-radial-menu-item slot=\"item\" icon=\"mi/baseline/delete\" tooltip=\"Elimina elemento\" variant=\"error\"></mds-radial-menu-item>\n</mds-radial-menu>\n```\n"
|
|
24597
24803
|
},
|
|
@@ -26696,7 +26902,7 @@
|
|
|
26696
26902
|
}
|
|
26697
26903
|
],
|
|
26698
26904
|
"usage": {
|
|
26699
|
-
"1. Description": "The `<mds-tab>` web component is the compound container that orchestrates a tabbed navigation in the Magma Design System. It is the parent wrapper around a set of `<mds-tab-item>` triggers and, when the component shows the content itself, their content panels, providing the ARIA `tablist` structure, selection state, scrolling and the animated selection indicator.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects `<mds-tab-item>` elements in the default slot; each panel in the named `content` slot is wired up automatically and paired by document order. The panels are optional: without them the component shows the strip alone, and the page shows the content, driven by `mdsTabChange` or by navigation.\n- **Navigation strip**: When every item has `href`, the items are links (announced as such, the selected one as current) and the strip is no longer a `tablist`: the browser follows the links, in a new tab on a modifier or middle click, and the strip keeps the selected item highlighted. A client-side router cancels the click on the item with `preventDefault()` and routes; a modifier click leaves the selection alone.\n- **Selection ownership**: The active tab is whichever `<mds-tab-item>` carries `selected`; the parent flips `selected` across siblings, shows the corresponding content panel and hides the rest.\n- **Change event**: Emits `mdsTabChange` with the selected item's index (`id`) and `value` whenever the active child changes.\n- **Focus restoration**: After a keyboard activation it re-focuses the selected item's button, so the user does not have to re-locate the tab.\n- **Auto-scroll into view**: On selection or child focus, the active tab is scrolled to the center of its strip.\n- **Overflow tracking**: When `overflow` is enabled, left/right inset shadows appear while the tabs overflow their container.\n- **Size propagation**: The parent `size` is pushed down onto every nested `<mds-tab-item>`, so children should not be sized individually.\n\n#### Properties & Visual Configurations\n\n- **`direction`** chooses whether the tab strip is laid out `'horizontal'` (default) or `'vertical'`.\n- **`animation`** governs the transition between active items: `'slide'` (default) renders the moving slider indicator, while `'fade'` cross-fades without the slider.\n- **`fill`** makes the tab strip stretch to occupy the full available width rather than hugging its content.\n- **`overflow`** enables the inset-shadow affordance that signals more tabs exist beyond the visible edges; **`scrollbar`** instead exposes the native horizontal scrollbar for accessibility.\n\n#### Other behavioral props\n\n- **`size`** sets the scale (`'sm'` / `'md'`) for the whole group and is forwarded to the child items; it is the only way to size the tabs consistently.\n",
|
|
26905
|
+
"1. Description": "The `<mds-tab>` web component is the compound container that orchestrates a tabbed navigation in the Magma Design System. It is the parent wrapper around a set of `<mds-tab-item>` triggers and, when the component shows the content itself, their content panels, providing the ARIA `tablist` structure, selection state, scrolling and the animated selection indicator.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects `<mds-tab-item>` elements in the default slot; each panel in the named `content` slot is wired up automatically and paired by document order. The panels are optional: without them the component shows the strip alone, and the page shows the content, driven by `mdsTabChange` or by navigation.\n- **Navigation strip**: When every item has `href`, the items are links (announced as such, the selected one as current) and the strip is no longer a `tablist`: the browser follows the links, in a new tab on a modifier or middle click, and the strip keeps the selected item highlighted. A client-side router cancels the click on the item with `preventDefault()` and routes; a modifier click leaves the selection alone.\n- **Selection ownership**: The active tab is whichever `<mds-tab-item>` carries `selected`; the parent flips `selected` across siblings, shows the corresponding content panel and hides the rest.\n- **Change event**: Emits `mdsTabChange` with the selected item's index (`id`) and `value` whenever the active child changes.\n- **Focus restoration**: After a keyboard activation it re-focuses the selected item's button, so the user does not have to re-locate the tab.\n- **Auto-scroll into view**: On selection or child focus, the active tab is scrolled to the center of its strip.\n- **Overflow tracking**: When `overflow` is enabled, left/right inset shadows appear while the tabs overflow their container.\n- **Size propagation**: The parent `size` is pushed down onto every nested `<mds-tab-item>`, so children should not be sized individually.\n\n#### Properties & Visual Configurations\n\n- **`direction`** chooses whether the tab strip is laid out `'horizontal'` (default) or `'vertical'`.\n- **`animation`** governs the transition between active items: `'slide'` (default) renders the moving slider indicator, while `'fade'` cross-fades without the slider. The slider slides only when the selection changes: on load, and when the strip is shown again after being hidden, it is already under the selected tab.\n- **`fill`** makes the tab strip stretch to occupy the full available width rather than hugging its content.\n- **`overflow`** enables the inset-shadow affordance that signals more tabs exist beyond the visible edges; **`scrollbar`** instead exposes the native horizontal scrollbar for accessibility.\n\n#### Other behavioral props\n\n- **`size`** sets the scale (`'sm'` / `'md'`) for the whole group and is forwarded to the child items; it is the only way to size the tabs consistently.\n",
|
|
26700
26906
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-tab>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Tab Group with Managed Panels\n\nThe canonical form. Put `<mds-tab-item>` elements in the default slot and one content element per tab in the named `content` slot. Mark the initially-visible tab with `selected`. Panels are wired up by document order - the first `[slot=content]` element is paired with the first `<mds-tab-item>`.\n\n```html\n<mds-tab>\n <mds-tab-item label=\"Panoramica\" selected></mds-tab-item>\n <mds-tab-item label=\"Dettagli\"></mds-tab-item>\n <mds-tab-item label=\"Allegati\"></mds-tab-item>\n\n <div slot=\"content\">\n <mds-text>Contenuto della scheda Panoramica.</mds-text>\n </div>\n <div slot=\"content\">\n <mds-text>Contenuto della scheda Dettagli.</mds-text>\n </div>\n <div slot=\"content\">\n <mds-text>Contenuto della scheda Allegati.</mds-text>\n </div>\n</mds-tab>\n```\n\n#### Listening to Tab Changes\n\nListen to the `mdsTabChange` event to react when the active panel changes. The event detail carries the zero-based `id` (index) and the optional `value` of the newly selected `<mds-tab-item>`.\n\n```html\n<mds-tab id=\"schede-pratica\">\n <mds-tab-item label=\"Anagrafica\" value=\"anagrafica\" selected></mds-tab-item>\n <mds-tab-item label=\"Documenti\" value=\"documenti\"></mds-tab-item>\n <mds-tab-item label=\"Pagamenti\" value=\"pagamenti\"></mds-tab-item>\n</mds-tab>\n\n<script>\n document.querySelector('#schede-pratica').addEventListener('mdsTabChange', (e) => {\n console.log('scheda attiva:', e.detail.id, e.detail.value);\n });\n</script>\n```\n\n#### Tab Items with Icons\n\nPass an icon slug to `<mds-tab-item>` via the `icon` prop. Icon position defaults to `left`; use `icon-position=\"right\"` for forward-navigation tabs.\n\n```html\n<mds-tab>\n <mds-tab-item label=\"Utente\" icon=\"mi/baseline/person\" selected></mds-tab-item>\n <mds-tab-item label=\"Impostazioni\" icon=\"mi/baseline/settings\"></mds-tab-item>\n <mds-tab-item label=\"Notifiche\" icon=\"mi/baseline/notifications\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Profilo utente.</mds-text></div>\n <div slot=\"content\"><mds-text>Impostazioni account.</mds-text></div>\n <div slot=\"content\"><mds-text>Cronologia notifiche.</mds-text></div>\n</mds-tab>\n```\n\n#### Fill the Available Width\n\nSet `fill` when the tab strip should stretch to occupy the full container width instead of hugging its content.\n\n```html\n<mds-tab fill>\n <mds-tab-item label=\"Riepilogo\" selected></mds-tab-item>\n <mds-tab-item label=\"Cronologia\"></mds-tab-item>\n <mds-tab-item label=\"Statistiche\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Riepilogo pratica.</mds-text></div>\n <div slot=\"content\"><mds-text>Registro modifiche.</mds-text></div>\n <div slot=\"content\"><mds-text>Dati statistici.</mds-text></div>\n</mds-tab>\n```\n\n#### Vertical Direction\n\nUse `direction=\"vertical\"` to stack the tab strip on the side. Pair it with `--mds-tab-direction-vertical-columns` to control the column widths of the sidebar and the content area.\n\n```html\n<mds-tab direction=\"vertical\">\n <mds-tab-item label=\"Dati generali\" selected></mds-tab-item>\n <mds-tab-item label=\"Indirizzi\"></mds-tab-item>\n <mds-tab-item label=\"Contatti\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Dati generali.</mds-text></div>\n <div slot=\"content\"><mds-text>Indirizzi registrati.</mds-text></div>\n <div slot=\"content\"><mds-text>Recapiti di contatto.</mds-text></div>\n</mds-tab>\n```\n\n#### Fade Animation\n\nSwitch to `animation=\"fade\"` to highlight the selected tab in place instead of moving the slider indicator. The panels switch without animation in both modes.\n\n```html\n<mds-tab animation=\"fade\">\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n <mds-tab-item label=\"Seconda\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Pannello 1.</mds-text></div>\n <div slot=\"content\"><mds-text>Pannello 2.</mds-text></div>\n</mds-tab>\n```\n\n#### Overflow Shadow for Many Tabs\n\nEnable `overflow` when the tab strip can contain more items than the viewport permits. Left and right inset shadows appear whenever tabs overflow their container, signalling that scrolling is possible.\n\n```html\n<mds-tab overflow>\n <mds-tab-item label=\"Gennaio\" selected></mds-tab-item>\n <mds-tab-item label=\"Febbraio\"></mds-tab-item>\n <mds-tab-item label=\"Marzo\"></mds-tab-item>\n <mds-tab-item label=\"Aprile\"></mds-tab-item>\n <mds-tab-item label=\"Maggio\"></mds-tab-item>\n <mds-tab-item label=\"Giugno\"></mds-tab-item>\n <mds-tab-item label=\"Luglio\"></mds-tab-item>\n <mds-tab-item label=\"Agosto\"></mds-tab-item>\n <mds-tab-item label=\"Settembre\"></mds-tab-item>\n <mds-tab-item label=\"Ottobre\"></mds-tab-item>\n <mds-tab-item label=\"Novembre\"></mds-tab-item>\n <mds-tab-item label=\"Dicembre\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Scrollbar for Accessible Overflow\n\nUse `scrollbar` instead of (or alongside) `overflow` to expose the native horizontal scrollbar. This is the accessible complement for users who navigate via keyboard or who have motor difficulties.\n\n```html\n<mds-tab scrollbar overflow>\n <mds-tab-item label=\"Sezione A\" selected></mds-tab-item>\n <mds-tab-item label=\"Sezione B\"></mds-tab-item>\n <mds-tab-item label=\"Sezione C\"></mds-tab-item>\n <mds-tab-item label=\"Sezione D\"></mds-tab-item>\n <mds-tab-item label=\"Sezione E\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Sizing\n\nSet `size` on the parent to scale all tabs uniformly. Do not set `size` on individual `<mds-tab-item>` elements - the parent propagates the value automatically.\n\n```html\n<!-- Compact strip, e.g. inside a sidebar or dense toolbar -->\n<mds-tab size=\"sm\">\n <mds-tab-item label=\"Vista elenco\" selected></mds-tab-item>\n <mds-tab-item label=\"Vista griglia\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Navigation Links (href on Tab Items)\n\nWhen each tab leads to an anchor, another page or a route, set `href` on every `<mds-tab-item>` and omit the `content` slot: the items render as links, the browser follows them (in a new tab on a modifier or middle click) and the strip keeps the selected item highlighted. The page content is driven by navigation, not by the managed-panels mechanism.\n\n```html\n<mds-tab>\n <mds-tab-item href=\"#sezione-1\" label=\"Introduzione\" selected></mds-tab-item>\n <mds-tab-item href=\"#sezione-2\" label=\"Requisiti\"></mds-tab-item>\n <mds-tab-item href=\"#sezione-3\" label=\"Conclusioni\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Client-Side Routing (href on Tab Items)\n\nIn a single-page app keep `href` on the items and register the router once with `NavigationService`, from `@maggioli-design-system/magma/services`: a plain click on an item is routed on the client and the selection still moves, with no listener per item. A modifier or middle click stays with the browser, which opens the link in a new tab while the strip stays as it is.\n\n```html\n<mds-tab id=\"sezioni\">\n <mds-tab-item href=\"/pratiche\" label=\"Pratiche\" selected></mds-tab-item>\n <mds-tab-item href=\"/documenti\" label=\"Documenti\"></mds-tab-item>\n <mds-tab-item href=\"/pagamenti\" label=\"Pagamenti\"></mds-tab-item>\n</mds-tab>\n\n<script type=\"module\">\n import { NavigationService } from '@maggioli-design-system/magma/services';\n\n NavigationService.setHandler((href) => router.navigate(href));\n</script>\n```\n\nWithout a registered router, cancel the click on the items and route by hand: the component honours `preventDefault()` and still moves the selection. Leave a modifier click alone.\n\n```html\n<script>\n document.querySelectorAll('#sezioni mds-tab-item').forEach((item) => {\n item.addEventListener('click', (event) => {\n if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;\n event.preventDefault();\n router.navigate(item.href);\n });\n });\n</script>\n```\n\n#### Disabled Tab Item\n\nMark an individual tab as unavailable with `disabled`. The parent's selection mechanism skips it; the tab is removed from the tab order automatically.\n\n```html\n<mds-tab>\n <mds-tab-item label=\"Attivo\" selected></mds-tab-item>\n <mds-tab-item label=\"Non disponibile\" disabled></mds-tab-item>\n <mds-tab-item label=\"Altro\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Contenuto disponibile.</mds-text></div>\n <div slot=\"content\"><mds-text>Contenuto non disponibile.</mds-text></div>\n <div slot=\"content\"><mds-text>Altro contenuto.</mds-text></div>\n</mds-tab>\n```\n\n#### Styling Customization\n\nStyle the component only through its documented `--mds-tab-*` CSS custom properties. Set them on the host or a parent selector; use semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.scheda-primaria mds-tab {\n --mds-tab-tabs-background: rgb(var(--magma-accent-surface));\n --mds-tab-tabs-radius: var(--magma-radius-xl);\n --mds-tab-item-selected-background: rgb(var(--magma-accent-emphasis));\n --mds-tab-item-selected-color: rgb(var(--magma-accent-on-emphasis));\n --mds-tab-transition-duration: 0.3s;\n}\n```\n",
|
|
26701
26907
|
"3. Antipattern": "Common incorrect uses of `<mds-tab>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Size Individual Tab Items\n\nSetting `size` on a `<mds-tab-item>` directly is overridden by the parent at render time. Use the `size` prop on `<mds-tab>` to size all tabs uniformly.\n\n```html\n<!-- INCORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Elenco\" size=\"sm\" selected></mds-tab-item>\n <mds-tab-item label=\"Griglia\" size=\"sm\"></mds-tab-item>\n</mds-tab>\n\n<!-- CORRECT -->\n<mds-tab size=\"sm\">\n <mds-tab-item label=\"Elenco\" selected></mds-tab-item>\n <mds-tab-item label=\"Griglia\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Do Not Mix Tab Items and Content Panels Out of Order\n\nPanels in `slot=\"content\"` are wired to `<mds-tab-item>` elements by document order. A missing panel leaves its tab with no content, a wrong ordering shows the wrong panel when a tab is selected.\n\n```html\n<!-- INCORRECT: only two content panels for three tab items -->\n<mds-tab>\n <mds-tab-item label=\"A\" selected></mds-tab-item>\n <mds-tab-item label=\"B\"></mds-tab-item>\n <mds-tab-item label=\"C\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Pannello A.</mds-text></div>\n <div slot=\"content\"><mds-text>Pannello B.</mds-text></div>\n</mds-tab>\n\n<!-- CORRECT: one content panel per tab item, same order -->\n<mds-tab>\n <mds-tab-item label=\"A\" selected></mds-tab-item>\n <mds-tab-item label=\"B\"></mds-tab-item>\n <mds-tab-item label=\"C\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Pannello A.</mds-text></div>\n <div slot=\"content\"><mds-text>Pannello B.</mds-text></div>\n <div slot=\"content\"><mds-text>Pannello C.</mds-text></div>\n</mds-tab>\n```\n\n#### Do Not Mix Link Items and Panel Tabs in One Strip\n\nA strip is either a `tablist` of tabs, each controlling a panel, or a navigation of links (`href` on every item): a link inside a tablist is not a child the role allows, and assistive technology announces the strip wrong. Keep the link out of the strip, as an `<mds-button>` next to it.\n\n```html\n<!-- INCORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Dettagli\" selected></mds-tab-item>\n <mds-tab-item label=\"Allegati\"></mds-tab-item>\n <mds-tab-item label=\"Portale\" href=\"https://portale.example.com\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Dettagli.</mds-text></div>\n <div slot=\"content\"><mds-text>Allegati.</mds-text></div>\n <div slot=\"content\"></div>\n</mds-tab>\n\n<!-- CORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Dettagli\" selected></mds-tab-item>\n <mds-tab-item label=\"Allegati\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Dettagli.</mds-text></div>\n <div slot=\"content\"><mds-text>Allegati.</mds-text></div>\n</mds-tab>\n<mds-button label=\"Portale\" href=\"https://portale.example.com\" target=\"blank\" tone=\"text\"></mds-button>\n```\n\n#### Do Not Put Tab Items Outside `<mds-tab>`\n\n`<mds-tab-item>` communicates with its parent through internal Stencil events. Used outside `<mds-tab>` it renders as an inert button with no selection, panel, or keyboard management.\n\n```html\n<!-- INCORRECT -->\n<div class=\"my-tab-wrapper\">\n <mds-tab-item label=\"Scheda uno\" selected></mds-tab-item>\n <mds-tab-item label=\"Scheda due\"></mds-tab-item>\n</div>\n<div>...</div>\n\n<!-- CORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Scheda uno\" selected></mds-tab-item>\n <mds-tab-item label=\"Scheda due\"></mds-tab-item>\n <div slot=\"content\">...</div>\n <div slot=\"content\">...</div>\n</mds-tab>\n```\n\n#### Do Not Listen to the `mdsTabItemSelect` Event from Outside\n\n`mdsTabItemSelect` is the item-level event that `<mds-tab-item>` fires to its parent `<mds-tab>`: its `detail` carries the item element (`target`) and `value`, not the position of the tab. To react to the active tab of the group listen to `mdsTabChange` on `<mds-tab>`, whose `detail` has the tab index (`id`) and `value`.\n\n```html\n<!-- INCORRECT -->\n<mds-tab id=\"schede\">\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n <mds-tab-item label=\"Seconda\"></mds-tab-item>\n</mds-tab>\n\n<script>\n document.querySelector('#schede').addEventListener('mdsTabItemSelect', handler);\n</script>\n\n<!-- CORRECT -->\n<mds-tab id=\"schede\">\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n <mds-tab-item label=\"Seconda\"></mds-tab-item>\n</mds-tab>\n\n<script>\n document.querySelector('#schede').addEventListener('mdsTabChange', handler);\n</script>\n```\n\n#### Do Not Use `scrollbar=\"false\"` or `overflow=\"false\"` to Turn Off Boolean Props\n\nStencil reads `\"false\"` as `false` and, since both props are reflected, removes the attribute at the first render, so this happens to work; but the markup says the opposite of what it does, and on a prop that is not reflected the attribute stays in the DOM, where `[attr]` selectors still match it. Remove the attribute entirely to turn a prop off.\n\n```html\n<!-- INCORRECT -->\n<mds-tab scrollbar=\"false\" overflow=\"false\">\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n</mds-tab>\n\n<!-- CORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n</mds-tab>\n```\n\n#### Do Not Place Raw HTML Instead of `<mds-tab-item>` in the Default Slot\n\nThe default slot expects `<mds-tab-item>` elements only. Placing a raw `<button>` or `<a>` there bypasses the ARIA `tablist` structure, selection management, and keyboard handling that `<mds-tab>` provides.\n\n```html\n<!-- INCORRECT -->\n<mds-tab>\n <button class=\"tab\">Documenti</button>\n <button class=\"tab\">Messaggi</button>\n <div slot=\"content\">...</div>\n <div slot=\"content\">...</div>\n</mds-tab>\n\n<!-- CORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Documenti\" selected></mds-tab-item>\n <mds-tab-item label=\"Messaggi\"></mds-tab-item>\n <div slot=\"content\">...</div>\n <div slot=\"content\">...</div>\n</mds-tab>\n```\n\n#### Do Not Customize via Undocumented Shadow Parts or Internal Selectors\n\nThe supported customization surface is the `--mds-tab-*` CSS custom properties and the documented shadow parts (`tabs`, `contents`, `slider`). Targeting other internals via `>>>`, `/deep/`, or undocumented class names couples your code to the shadow DOM implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-tab >>> .tabs-wrapper {\n background: red;\n}\nmds-tab::part(tabs-wrapper) {\n padding: 0;\n}\n\n/* CORRECT */\nmds-tab {\n --mds-tab-tabs-background: rgb(var(--magma-accent-surface));\n --mds-tab-tabs-padding: calc(var(--spacing) * 400);\n --mds-tab-tabs-radius: var(--magma-radius-xl);\n}\nmds-tab::part(tabs) {\n outline: 2px solid rgb(var(--magma-accent-border));\n}\n```\n"
|
|
26702
26908
|
},
|
|
@@ -28013,8 +28219,8 @@
|
|
|
28013
28219
|
}
|
|
28014
28220
|
],
|
|
28015
28221
|
"usage": {
|
|
28016
|
-
"1. Description": "The `<mds-table>` web component is the root container of the Magma Design System tabular data system. It wraps a native `<table>` and orchestrates a family of compound children (`mds-table-header`, `mds-table-body`, `mds-table-footer`, `mds-table-row`, `mds-table-cell`), propagating interaction, selection, and overflow state down to them.\n\n#### Semantic Behavior\n\n- **Compound parent**: The default slot must hold `mds-table-header` / `mds-table-body` / `mds-table-footer`; `<mds-table>` pushes its own `interactive` and `selectable` state onto every `mds-table-row` and the header/body. It is not used standalone.\n- **Selection model**: When `selectable` is set, rows expose a checkbox; the component aggregates the selected rows, mirrors the count to the header's tristate control, and flags that a selection exists so it is visible to CSS and consumers.\n- **Selection event**: Emits `mdsTableSelectionChange` (bubbles, composed) carrying `{ rows }`, an array of `{ index, value }` for every selected row. Selection is driven via the `updateSelection()` and `selectAll(select?)` methods rather than DOM listeners; both are no-ops unless `selectable` is true.\n- **Live children**: Rows added or removed at runtime are re-wired with the table's interactive and selectable state, so dynamically added rows behave consistently.\n- **Action overflow**: When rows carry a `[slot=\"action\"]`, rows flip into an overlaid-action mode once content exceeds the visible width.\n- **Localization**: Resolves its display language from the page (`<html lang>`: `el`/`en`/`es`/`it`, otherwise `en`) for the batch-actions label.\n\n#### Properties & Visual Configurations\n\n- **`interactive`** highlights rows on mouseover; choose it for tables whose rows are clickable or navigable, not for purely static read-only data.\n- **`selectable`** turns on per-row checkbox selection and the aggregated header/batch-actions machinery; without it the selection methods and the `batch-action` slot are inert.\n- **`selection`** is a read-back flag that becomes true while at least one row is selected - it is managed internally, not something callers normally set.\n\n#### Other behavioral props\n\n- **`batch-action` slot** holds `mds-button` element/s; its bar renders only when `selectable` is on and at least one batch action is slotted, surfacing a live count badge of the current selection.\n",
|
|
28017
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-table>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Read-Only Table\n\nThe minimal structure: `mds-table-header` with one `mds-table-header-cell` per column, `mds-table-body` with `mds-table-row` children each containing `mds-table-cell` elements. All four subparts are required direct children - do not replace them with raw `<thead>`, `<tr>`, or `<td>` elements.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data iscrizione\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">mario.rossi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">12 ottobre 1985</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Luigi Verdi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">luigi.verdi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">3 marzo 1993</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Layout: Fill the Container and Let the Table Scroll\n\n`<mds-table>` scrolls on its own: its rows sit in an inner wrapper with `overflow: auto`, so when the columns are wider than the table, the table scrolls horizontally inside its own border, and the row actions (`slot=\"action\"`) stay pinned to the visible right edge. It needs no `overflow-x-auto` wrapper of yours, but it needs two things from the page:\n\n- **All the width its container offers**: `w-full` on `<mds-table>`. When that container is a flex or grid item (a `main` next to a sidebar, a `1fr` column), also give the item `min-w-0`: a flex or grid item never shrinks below its content by default, so without it the item grows to the full width of the table and the whole page scrolls instead of the table.\n- **Cells on one line**: `text-wrap: nowrap` on the cells (`[&_mds-table-cell]:text-nowrap` on the table). Wrapping cells squeeze the columns into tall rows and the table never scrolls. `mds-text` with `typography` `paragraph`, `detail` or `caption` sets its own `text-wrap: pretty`, which wins over what it inherits from the cell, so target it too (`[&_mds-text]:text-nowrap`). A long free-text column can keep wrapping if it reads better.\n\n```html\n<div class=\"flex\">\n <aside class=\"w-6400 shrink-0\">...</aside>\n <main class=\"min-w-0 flex-1\">\n <mds-table class=\"w-full [&_mds-table-cell]:text-nowrap [&_mds-text]:text-nowrap\">\n <mds-table-header>\n <mds-table-header-cell label=\"Protocollo\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Oggetto\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ufficio\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">2026/0412</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Contratto di fornitura servizi cloud 2026-2028</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Ufficio acquisti e gare</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">12 marzo 2026</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n </mds-table>\n </main>\n</div>\n```\n\nTo scroll vertically as well, bound the table's height: in a fixed-height panel, make the panel a flex column and give the table `flex-1 min-h-0` (or put `h-full` or a `max-h-*` on the table). The header row scrolls with the body, it is not sticky.\n\n```html\n<section class=\"flex h-9600 flex-col\">\n <mds-table class=\"min-h-0 flex-1 [&_mds-table-cell]:text-nowrap [&_mds-text]:text-nowrap\">\n ...\n </mds-table>\n</section>\n```\n\nWithout Tailwind, the same rules in CSS:\n\n```css\n.content {\n min-width: 0;\n}\n\n.content mds-table {\n width: 100%;\n}\n\n.content mds-table-cell,\n.content mds-table-cell mds-text {\n text-wrap: nowrap;\n}\n```\n\n#### Table with Footer\n\nAdd `mds-table-footer` after `mds-table-body` to show totals or summaries. Each cell inside the footer is an `mds-table-cell` - the same component used in body rows.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Voce\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Importo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Servizio A</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">120,00 EUR</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Servizio B</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">80,00 EUR</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-table-footer>\n <mds-table-cell><mds-text typography=\"action\">Totale</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"action\">200,00 EUR</mds-text></mds-table-cell>\n </mds-table-footer>\n</mds-table>\n```\n\n#### Interactive Rows\n\nSet `interactive` when rows are clickable or navigable. The prop propagates to every `mds-table-row` and highlights the hovered row. Do not reach into rows directly to set `interactive` - set it once on the parent.\n\n```html\n<mds-table interactive>\n <mds-table-header>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ruolo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Anna Bianchi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Amministratore</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Carlo Neri</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Operatore</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Row-Level Action Buttons\n\nSlot `mds-button` elements with `slot=\"action\"` directly inside `mds-table-row` (not inside `mds-table-cell`). The table detects the presence of action buttons and switches to overlay-action mode automatically when content overflows the visible width.\n\n```html\n<mds-table interactive>\n <mds-table-header>\n <mds-table-header-cell label=\"Documento\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Contratto 2024.pdf</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Approvato</mds-text></mds-table-cell>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/download\"\n title=\"Scarica documento\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/delete\"\n title=\"Elimina documento\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Row Selection and Selection Event\n\nSet `selectable` to add a checkbox to each row. Listen for `mdsTableSelectionChange` to receive the array of selected rows - each entry carries the row `index` and the optional `value` set on `mds-table-row`. Assign `value` to each row to distinguish selections in the event payload.\n\n```html\n<mds-table selectable id=\"tabella-utenti\">\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Reparto\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"usr-001\">\n <mds-table-cell><mds-text typography=\"detail\">Giulia Russo</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Contabilita</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"usr-002\">\n <mds-table-cell><mds-text typography=\"detail\">Marco Ferrari</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">IT</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n document.getElementById('tabella-utenti').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n // e.detail.rows => [{ index: 0, value: 'usr-001' }, ...]\n });\n</script>\n```\n\n#### Programmatic Select All\n\nCall the `selectAll()` method to select all rows at once; pass `false` to deselect. This is a no-op unless `selectable` is set.\n\n```html\n<mds-button id=\"btn-seleziona-tutti\" label=\"Seleziona tutti\" variant=\"primary\" tone=\"outline\"></mds-button>\n<mds-button id=\"btn-deseleziona\" label=\"Deseleziona tutti\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-table selectable id=\"tabella-doc\">\n <mds-table-header>\n <mds-table-header-cell label=\"Titolo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"doc-1\">\n <mds-table-cell><mds-text typography=\"detail\">Verbale assemblea</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"doc-2\">\n <mds-table-cell><mds-text typography=\"detail\">Bilancio 2024</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n const table = document.getElementById('tabella-doc');\n document.getElementById('btn-seleziona-tutti').addEventListener('click', () => table.selectAll());\n document.getElementById('btn-deseleziona').addEventListener('click', () => table.selectAll(false));\n</script>\n```\n\n#### Batch Actions Bar\n\nSlot `mds-button` elements with `slot=\"batch-action\"` as direct children of `mds-table` alongside the body. The bar renders only when `selectable` is set and at least one batch-action button is present; it shows a live count badge of the current selection and appears once a row is checked.\n\n```html\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Pratica\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"prat-001\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica n. 1234</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">In lavorazione</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"prat-002\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica n. 5678</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Chiusa</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-button\n slot=\"batch-action\"\n icon=\"mi/outline/send\"\n label=\"Invia selezionati\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n <mds-button\n slot=\"batch-action\"\n icon=\"mi/outline/delete\"\n label=\"Elimina selezionati\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n</mds-table>\n```\n\n#### Styling Customization\n\nCustomize the table appearance only through its documented `--mds-table-*` CSS custom properties. Set them on the host element or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and themes keep working.\n\n```css\n.tabella-contratti mds-table {\n --mds-table-background: rgb(var(--magma-surface-raised));\n --mds-table-background-alt: rgb(var(--magma-surface-muted));\n --mds-table-border-color: rgb(var(--magma-accent-border));\n --mds-table-border-width: 1px;\n --mds-table-cell-padding: calc(var(--spacing) * 500);\n --mds-table-color: rgb(var(--magma-text-default));\n}\n```\n",
|
|
28222
|
+
"1. Description": "The `<mds-table>` web component is the root container of the Magma Design System tabular data system. It wraps a native `<table>` and orchestrates a family of compound children (`mds-table-header`, `mds-table-body`, `mds-table-footer`, `mds-table-row`, `mds-table-cell`), propagating interaction, selection, and overflow state down to them.\n\n#### Semantic Behavior\n\n- **Compound parent**: The default slot must hold `mds-table-header` / `mds-table-body` / `mds-table-footer`; `<mds-table>` pushes its own `interactive` and `selectable` state onto every `mds-table-row` and the header/body. It is not used standalone.\n- **Selection model**: When `selectable` is set, rows expose a checkbox; the component aggregates the selected rows, mirrors the count to the header's tristate control, and flags that a selection exists so it is visible to CSS and consumers.\n- **Selection event**: Emits `mdsTableSelectionChange` (bubbles, composed) carrying `{ rows }`, an array of `{ index, value }` for every selected row. Selection is driven via the `updateSelection()` and `selectAll(select?)` methods rather than DOM listeners; both are no-ops unless `selectable` is true.\n- **Live children**: Rows added or removed at runtime are re-wired with the table's interactive and selectable state, so dynamically added rows behave consistently.\n- **Action overflow**: When rows carry a `[slot=\"action\"]`, rows flip into an overlaid-action mode once content exceeds the visible width.\n- **Localization**: Resolves its display language from the page (`<html lang>`: `el`/`en`/`es`/`it`, otherwise `en`) for the batch-actions label.\n\n#### Properties & Visual Configurations\n\n- **`interactive`** highlights rows on mouseover; choose it for tables whose rows are clickable or navigable, not for purely static read-only data.\n- **`selectable`** turns on per-row checkbox selection and the aggregated header/batch-actions machinery; without it the selection methods and the `batch-action` slot are inert.\n- **`selection`** is a read-back flag that becomes true while at least one row is selected - it is managed internally, not something callers normally set.\n- **`sorting`** says who orders the rows when a sortable `mds-table-header-cell` changes direction. `internal` (default) moves the rows in the DOM; `external` leaves them where they are, so the application listens to `mdsTableHeaderCellSort` and renders the rows in the order asked. Choose `external` whenever the table shows one page of a larger set (with `mds-paginator`) or the order comes from a back end: sorting the DOM would only sort the page on screen.\n\n#### Other behavioral props\n\n- **`batch-action` slot** holds `mds-button` element/s; its bar renders only when `selectable` is on and at least one batch action is slotted, surfacing a live count badge of the current selection.\n",
|
|
28223
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-table>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Read-Only Table\n\nThe minimal structure: `mds-table-header` with one `mds-table-header-cell` per column, `mds-table-body` with `mds-table-row` children each containing `mds-table-cell` elements. All four subparts are required direct children - do not replace them with raw `<thead>`, `<tr>`, or `<td>` elements.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data iscrizione\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">mario.rossi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">12 ottobre 1985</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Luigi Verdi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">luigi.verdi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">3 marzo 1993</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Layout: Fill the Container and Let the Table Scroll\n\n`<mds-table>` scrolls on its own: its rows sit in an inner wrapper with `overflow: auto`, so when the columns are wider than the table, the table scrolls horizontally inside its own border, and the row actions (`slot=\"action\"`) stay pinned to the visible right edge. It needs no `overflow-x-auto` wrapper of yours, but it needs two things from the page:\n\n- **All the width its container offers**: `w-full` on `<mds-table>`. When that container is a flex or grid item (a `main` next to a sidebar, a `1fr` column), also give the item `min-w-0`: a flex or grid item never shrinks below its content by default, so without it the item grows to the full width of the table and the whole page scrolls instead of the table.\n- **Cells on one line**: `text-wrap: nowrap` on the cells (`[&_mds-table-cell]:text-nowrap` on the table). Wrapping cells squeeze the columns into tall rows and the table never scrolls. `mds-text` with `typography` `paragraph`, `detail` or `caption` sets its own `text-wrap: pretty`, which wins over what it inherits from the cell, so target it too (`[&_mds-text]:text-nowrap`). A long free-text column can keep wrapping if it reads better.\n\n```html\n<div class=\"flex\">\n <aside class=\"w-6400 shrink-0\">...</aside>\n <main class=\"min-w-0 flex-1\">\n <mds-table class=\"w-full [&_mds-table-cell]:text-nowrap [&_mds-text]:text-nowrap\">\n <mds-table-header>\n <mds-table-header-cell label=\"Protocollo\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Oggetto\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ufficio\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">2026/0412</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Contratto di fornitura servizi cloud 2026-2028</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Ufficio acquisti e gare</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">12 marzo 2026</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n </mds-table>\n </main>\n</div>\n```\n\nTo scroll vertically as well, bound the table's height: in a fixed-height panel, make the panel a flex column and give the table `flex-1 min-h-0` (or put `h-full` or a `max-h-*` on the table). The header row scrolls with the body, it is not sticky.\n\n```html\n<section class=\"flex h-9600 flex-col\">\n <mds-table class=\"min-h-0 flex-1 [&_mds-table-cell]:text-nowrap [&_mds-text]:text-nowrap\">\n ...\n </mds-table>\n</section>\n```\n\nWithout Tailwind, the same rules in CSS:\n\n```css\n.content {\n min-width: 0;\n}\n\n.content mds-table {\n width: 100%;\n}\n\n.content mds-table-cell,\n.content mds-table-cell mds-text {\n text-wrap: nowrap;\n}\n```\n\n#### Table with Footer\n\nAdd `mds-table-footer` after `mds-table-body` to show totals or summaries. Each cell inside the footer is an `mds-table-cell` - the same component used in body rows.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Voce\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Importo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Servizio A</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">120,00 EUR</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Servizio B</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">80,00 EUR</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-table-footer>\n <mds-table-cell><mds-text typography=\"action\">Totale</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"action\">200,00 EUR</mds-text></mds-table-cell>\n </mds-table-footer>\n</mds-table>\n```\n\n#### Interactive Rows\n\nSet `interactive` when rows are clickable or navigable. The prop propagates to every `mds-table-row` and highlights the hovered row. Do not reach into rows directly to set `interactive` - set it once on the parent.\n\n```html\n<mds-table interactive>\n <mds-table-header>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ruolo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Anna Bianchi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Amministratore</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Carlo Neri</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Operatore</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Row-Level Action Buttons\n\nSlot `mds-button` elements with `slot=\"action\"` directly inside `mds-table-row` (not inside `mds-table-cell`). The table detects the presence of action buttons and switches to overlay-action mode automatically when content overflows the visible width.\n\n```html\n<mds-table interactive>\n <mds-table-header>\n <mds-table-header-cell label=\"Documento\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Contratto 2024.pdf</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Approvato</mds-text></mds-table-cell>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/download\"\n title=\"Scarica documento\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/delete\"\n title=\"Elimina documento\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Row Selection and Selection Event\n\nSet `selectable` to add a checkbox to each row. Listen for `mdsTableSelectionChange` to receive the array of selected rows - each entry carries the row `index` and the optional `value` set on `mds-table-row`. Assign `value` to each row to distinguish selections in the event payload.\n\n```html\n<mds-table selectable id=\"tabella-utenti\">\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Reparto\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"usr-001\">\n <mds-table-cell><mds-text typography=\"detail\">Giulia Russo</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Contabilita</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"usr-002\">\n <mds-table-cell><mds-text typography=\"detail\">Marco Ferrari</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">IT</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n document.getElementById('tabella-utenti').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n // e.detail.rows => [{ index: 0, value: 'usr-001' }, ...]\n });\n</script>\n```\n\n#### Programmatic Select All\n\nCall the `selectAll()` method to select all rows at once; pass `false` to deselect. This is a no-op unless `selectable` is set.\n\n```html\n<mds-button id=\"btn-seleziona-tutti\" label=\"Seleziona tutti\" variant=\"primary\" tone=\"outline\"></mds-button>\n<mds-button id=\"btn-deseleziona\" label=\"Deseleziona tutti\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-table selectable id=\"tabella-doc\">\n <mds-table-header>\n <mds-table-header-cell label=\"Titolo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"doc-1\">\n <mds-table-cell><mds-text typography=\"detail\">Verbale assemblea</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"doc-2\">\n <mds-table-cell><mds-text typography=\"detail\">Bilancio 2024</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n const table = document.getElementById('tabella-doc');\n document.getElementById('btn-seleziona-tutti').addEventListener('click', () => table.selectAll());\n document.getElementById('btn-deseleziona').addEventListener('click', () => table.selectAll(false));\n</script>\n```\n\n#### Batch Actions Bar\n\nSlot `mds-button` elements with `slot=\"batch-action\"` as direct children of `mds-table` alongside the body. The bar renders only when `selectable` is set and at least one batch-action button is present; it shows a live count badge of the current selection and appears once a row is checked.\n\n```html\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Pratica\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"prat-001\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica n. 1234</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">In lavorazione</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"prat-002\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica n. 5678</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Chiusa</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-button\n slot=\"batch-action\"\n icon=\"mi/outline/send\"\n label=\"Invia selezionati\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n <mds-button\n slot=\"batch-action\"\n icon=\"mi/outline/delete\"\n label=\"Elimina selezionati\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n</mds-table>\n```\n\n#### Sorting by the Back End, with Pages\n\nWhen the table shows one page of a larger set, set `sorting=\"external\"`: a click on a sortable header emits `mdsTableHeaderCellSort` with the column (`index`, and `sortKey` when the cell has `sort-key`) and the `direction`, and moves no row. The application asks the back end for the first page in that order and renders it; the header shows the direction (icon and `aria-sort`). A `direction` set by the application, for example restored from the address, is shown the same way.\n\n```html\n<mds-table id=\"practices\" sorting=\"external\">\n <mds-table-header>\n <mds-table-header-cell label=\"Numero\" sortable sort-key=\"number\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ricevuta il\" sortable sort-key=\"received\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Oggetto\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <!-- the rows of the current page, rendered by the application -->\n </mds-table-body>\n</mds-table>\n<mds-paginator id=\"pages\" pages=\"12\"></mds-paginator>\n```\n\n```js\nconst table = document.querySelector('#practices');\nconst pages = document.querySelector('#pages');\n\ntable.addEventListener('mdsTableHeaderCellSort', async (event) => {\n const { sortKey, direction } = event.detail;\n // direction \"none\" asks for the order of the back end\n await loadPage({ page: 1, sort: direction === 'none' ? undefined : { sortKey, direction } });\n pages.currentPage = 1;\n});\n```\n\n#### Styling Customization\n\nCustomize the table appearance only through its documented `--mds-table-*` CSS custom properties. Set them on the host element or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and themes keep working.\n\n```css\n.tabella-contratti mds-table {\n --mds-table-background: rgb(var(--magma-surface-raised));\n --mds-table-background-alt: rgb(var(--magma-surface-muted));\n --mds-table-border-color: rgb(var(--magma-accent-border));\n --mds-table-border-width: 1px;\n --mds-table-cell-padding: calc(var(--spacing) * 500);\n --mds-table-color: rgb(var(--magma-text-default));\n}\n```\n",
|
|
28018
28224
|
"3. Antipattern": "Common incorrect uses of `<mds-table>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Replace Compound Subparts with Raw HTML Elements\n\n`<mds-table>` orchestrates its children via internal Stencil mechanisms. Substituting any subpart (`mds-table-header`, `mds-table-body`, `mds-table-row`, `mds-table-cell`) with a raw `<thead>`, `<tbody>`, `<tr>`, or `<td>` breaks propagation of `interactive`, `selectable`, and overflow state.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <thead>\n <tr><th>Nome</th><th>Email</th></tr>\n </thead>\n <tbody>\n <tr><td>Mario Rossi</td><td>mario.rossi@example.com</td></tr>\n </tbody>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">mario.rossi@example.com</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Do Not Slot Batch-Action Buttons Inside the Body\n\nThe `slot=\"batch-action\"` must be a direct child of `<mds-table>`, not nested inside `mds-table-body` or any row. The component queries `:scope > [slot=\"batch-action\"]` at load time and the bar will not appear if the slot is misplaced.\n\n```html\n<!-- INCORRECT -->\n<mds-table selectable>\n <mds-table-body>\n <mds-table-row>...</mds-table-row>\n <mds-button slot=\"batch-action\" label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table selectable>\n <mds-table-header>...</mds-table-header>\n <mds-table-body>\n <mds-table-row>...</mds-table-row>\n </mds-table-body>\n <mds-button slot=\"batch-action\" label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-table>\n```\n\n#### Do Not Slot Row Action Buttons Inside `mds-table-cell`\n\nPer-row action buttons use `slot=\"action\"` on a direct child of `mds-table-row`, not wrapped inside an `mds-table-cell`. Placing them in a cell hides them (`mds-table-cell` has no `action` slot, so the button is not rendered) and breaks the overflow-detection logic that switches rows into overlay-action mode.\n\n```html\n<!-- INCORRECT -->\n<mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Contratto.pdf</mds-text></mds-table-cell>\n <mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" title=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-table-cell>\n</mds-table-row>\n\n<!-- CORRECT -->\n<mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Contratto.pdf</mds-text></mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" title=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-table-row>\n```\n\n#### Do Not Enable Batch Actions Without `selectable`\n\nThe batch-action bar only renders when `selectable` is set. Slotting batch-action buttons on a non-selectable table silently produces no bar and no selection count, causing the buttons to never appear.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header>...</mds-table-header>\n <mds-table-body>...</mds-table-body>\n <mds-button slot=\"batch-action\" label=\"Esporta\" variant=\"primary\"></mds-button>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table selectable>\n <mds-table-header>...</mds-table-header>\n <mds-table-body>...</mds-table-body>\n <mds-button slot=\"batch-action\" label=\"Esporta\" variant=\"primary\"></mds-button>\n</mds-table>\n```\n\n#### Do Not Set `interactive` on Individual Rows\n\n`interactive` is a table-level prop that propagates automatically to every `mds-table-row`. Setting it directly on individual rows bypasses the table's state management and leads to inconsistent behavior when rows are added or removed at runtime.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-body>\n <mds-table-row interactive>...</mds-table-row>\n <mds-table-row>...</mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table interactive>\n <mds-table-body>\n <mds-table-row>...</mds-table-row>\n <mds-table-row>...</mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Do Not Listen for Native `change` Events to Track Selection\n\nSelection state is communicated via the `mdsTableSelectionChange` custom event. Native `change` events from the internal checkboxes do not bubble out of the shadow DOM reliably; always use the documented Magma event.\n\n```html\n<!-- INCORRECT -->\n<mds-table selectable id=\"tbl\">...</mds-table>\n<script>\n document.getElementById('tbl').addEventListener('change', (e) => {\n // unreliable - native events do not bubble from shadow DOM\n });\n</script>\n\n<!-- CORRECT -->\n<mds-table selectable id=\"tbl\">...</mds-table>\n<script>\n document.getElementById('tbl').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n });\n</script>\n```\n\n#### Do Not Set `selection` Manually\n\n`selection` is a reflected read-back attribute managed internally by the table. It becomes `true` when at least one row is selected and is intended for CSS attribute selectors or conditional logic in the host app. Setting it from outside does not change which rows are selected and will be overwritten on the next selection update. The table emits `mdsTableSelectionChange` before it updates `selection`, so inside that listener read `e.detail.rows`, not the attribute.\n\n```html\n<!-- INCORRECT -->\n<mds-table selectable selection>\n ...\n</mds-table>\n\n<!-- CORRECT - read it back, do not set it -->\n<mds-table selectable id=\"tbl\">\n ...\n</mds-table>\n<script>\n document.getElementById('tbl').addEventListener('mdsTableSelectionChange', (e) => {\n const hasSelection = e.detail.rows.length > 0;\n document.getElementById('panel-azioni').hidden = !hasSelection;\n });\n</script>\n```\n"
|
|
28019
28225
|
},
|
|
28020
28226
|
"props": [
|
|
@@ -28095,6 +28301,50 @@
|
|
|
28095
28301
|
"required": false,
|
|
28096
28302
|
"getter": false,
|
|
28097
28303
|
"setter": false
|
|
28304
|
+
},
|
|
28305
|
+
{
|
|
28306
|
+
"name": "sorting",
|
|
28307
|
+
"type": "\"external\" | \"internal\" | undefined",
|
|
28308
|
+
"complexType": {
|
|
28309
|
+
"original": "MdsTableSortingType",
|
|
28310
|
+
"resolved": "\"external\" | \"internal\" | undefined",
|
|
28311
|
+
"references": {
|
|
28312
|
+
"MdsTableSortingType": {
|
|
28313
|
+
"location": "import",
|
|
28314
|
+
"path": "./meta/type",
|
|
28315
|
+
"id": "src/components/mds-table/meta/type.ts::MdsTableSortingType",
|
|
28316
|
+
"referenceLocation": "MdsTableSortingType"
|
|
28317
|
+
}
|
|
28318
|
+
}
|
|
28319
|
+
},
|
|
28320
|
+
"mutable": false,
|
|
28321
|
+
"attr": "sorting",
|
|
28322
|
+
"reflectToAttr": true,
|
|
28323
|
+
"docs": "Specifies who sorts the rows when a sortable header cell changes direction: `internal` moves\nthem in the DOM, `external` leaves them to the application, which listens to\n`mdsTableHeaderCellSort` and renders the rows in the order asked (a table that shows one page\nof a larger set)",
|
|
28324
|
+
"docsTags": [
|
|
28325
|
+
{
|
|
28326
|
+
"name": "default",
|
|
28327
|
+
"text": "'internal'"
|
|
28328
|
+
}
|
|
28329
|
+
],
|
|
28330
|
+
"default": "'internal'",
|
|
28331
|
+
"values": [
|
|
28332
|
+
{
|
|
28333
|
+
"value": "external",
|
|
28334
|
+
"type": "string"
|
|
28335
|
+
},
|
|
28336
|
+
{
|
|
28337
|
+
"value": "internal",
|
|
28338
|
+
"type": "string"
|
|
28339
|
+
},
|
|
28340
|
+
{
|
|
28341
|
+
"type": "undefined"
|
|
28342
|
+
}
|
|
28343
|
+
],
|
|
28344
|
+
"optional": true,
|
|
28345
|
+
"required": false,
|
|
28346
|
+
"getter": false,
|
|
28347
|
+
"setter": false
|
|
28098
28348
|
}
|
|
28099
28349
|
],
|
|
28100
28350
|
"methods": [
|
|
@@ -28207,7 +28457,7 @@
|
|
|
28207
28457
|
{
|
|
28208
28458
|
"name": "--mds-table-background-alt",
|
|
28209
28459
|
"annotation": "prop",
|
|
28210
|
-
"docs": "Alternate background color for table rows."
|
|
28460
|
+
"docs": "Alternate background color for table rows; in an interactive table also the scroll area, while the pointer is on the table."
|
|
28211
28461
|
},
|
|
28212
28462
|
{
|
|
28213
28463
|
"name": "--mds-table-border-color",
|
|
@@ -28676,9 +28926,9 @@
|
|
|
28676
28926
|
"docs": "",
|
|
28677
28927
|
"docsTags": [],
|
|
28678
28928
|
"usage": {
|
|
28679
|
-
"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/AGENTS.md) 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
|
|
28680
|
-
"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 shared component rules in [`agents/conventions.md`](../../../../agents/conventions.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####
|
|
28681
|
-
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - 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
|
|
28929
|
+
"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/AGENTS.md) 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. With `sorting=\"external\"` on the table it moves no row: the application renders them in the order asked.\n- **Tri-state sort cycle**: Each activation advances the column through `none` -> `ascending` -> `descending` and back to `none`; the `none` state restores the order the rows had before any column sorted them (rows removed in the meantime stay out, rows added go last).\n- **Sort event**: Every click emits `mdsTableHeaderCellSort`, which bubbles to the table, with `{ direction, index, sortKey }`: the new direction, the position of the column and its `sort-key`. A `direction` set by the application emits nothing, the application already knows it.\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`), which drives the sort icon and `aria-sort`. Set from outside (or in the markup) it acts like the clicks that lead there: it sorts the rows, or only shows the order with `sorting=\"external\"`, resets the other columns to `none`, and the next click goes on from it.\n- **`sortKey`** (`sort-key`): Names the column in `mdsTableHeaderCellSort`, typically the field the back end sorts by, so the application does not depend on the position of the column.\n",
|
|
28930
|
+
"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 shared component rules in [`agents/conventions.md`](../../../../agents/conventions.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#### Setting the Direction from Outside\n\nSet `direction` to sort by a column without a click - for example from a sort order kept in the address. It sorts the rows as the clicks that lead there would, resets the other columns to `none`, and the next click goes on with the cycle from it. `none` brings back the original order. No `mdsTableHeaderCellSort` is emitted: the application set it.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Data\" sortable direction=\"descending\"></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\ndocument.querySelector('mds-table-header-cell').direction = 'none';\n```\n\n#### Sorting by the Back End\n\nWhen the table shows one page of a larger set, give the table `sorting=\"external\"` and each sortable column a `sort-key`. A click then moves no row: listen to `mdsTableHeaderCellSort` and load the rows in the order asked. See the pattern with `mds-paginator` in [`mds-table`](../mds-table/AGENTS.md).\n\n```html\n<mds-table sorting=\"external\">\n <mds-table-header>\n <mds-table-header-cell label=\"Numero\" sortable sort-key=\"number\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ricevuta il\" sortable sort-key=\"received\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <!-- the rows of the current page -->\n </mds-table-body>\n</mds-table>\n```\n\n```js\ndocument.querySelector('mds-table').addEventListener('mdsTableHeaderCellSort', (event) => {\n const { sortKey, direction } = event.detail; // 'received', 'descending'\n loadFirstPage(direction === 'none' ? undefined : { sortKey, direction });\n});\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",
|
|
28931
|
+
"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 [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - 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 Let the Cells Sort a Table with Pages\n\nBy default a sortable header cell reorders the rows in the DOM. On a table that shows one page of a larger set that sorts the page on screen, not the data: the first row is not the first of the set.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Numero\" sortable></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- one page of rows --></mds-table-body>\n</mds-table>\n<mds-paginator pages=\"12\"></mds-paginator>\n\n<!-- CORRECT - the back end sorts, after mdsTableHeaderCellSort -->\n<mds-table sorting=\"external\">\n <mds-table-header>\n <mds-table-header-cell label=\"Numero\" sortable sort-key=\"number\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- one page of rows --></mds-table-body>\n</mds-table>\n<mds-paginator pages=\"12\"></mds-paginator>\n```\n\n#### Do Not Use `sortable=\"false\"` to Disable Sorting\n\n`sortable` is a boolean attribute. Stencil reads the exact string `\"false\"` as `false`, but the attribute stays on the element, where attribute selectors and any code that tests for its presence still read it as set. 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"
|
|
28682
28932
|
},
|
|
28683
28933
|
"props": [
|
|
28684
28934
|
{
|
|
@@ -28699,7 +28949,7 @@
|
|
|
28699
28949
|
"mutable": true,
|
|
28700
28950
|
"attr": "direction",
|
|
28701
28951
|
"reflectToAttr": true,
|
|
28702
|
-
"docs": "Specifies the current sort direction of the column.",
|
|
28952
|
+
"docs": "Specifies the current sort direction of the column. Set from outside, it sorts the rows like a\nclick, or only shows the order when the table has `sorting=\"external\"`.",
|
|
28703
28953
|
"docsTags": [
|
|
28704
28954
|
{
|
|
28705
28955
|
"name": "default",
|
|
@@ -28752,6 +29002,32 @@
|
|
|
28752
29002
|
"getter": false,
|
|
28753
29003
|
"setter": false
|
|
28754
29004
|
},
|
|
29005
|
+
{
|
|
29006
|
+
"name": "sortKey",
|
|
29007
|
+
"type": "string | undefined",
|
|
29008
|
+
"complexType": {
|
|
29009
|
+
"original": "string",
|
|
29010
|
+
"resolved": "string | undefined",
|
|
29011
|
+
"references": {}
|
|
29012
|
+
},
|
|
29013
|
+
"mutable": false,
|
|
29014
|
+
"attr": "sort-key",
|
|
29015
|
+
"reflectToAttr": true,
|
|
29016
|
+
"docs": "Names the column in the `mdsTableHeaderCellSort` event, for example the field the back end\nsorts by",
|
|
29017
|
+
"docsTags": [],
|
|
29018
|
+
"values": [
|
|
29019
|
+
{
|
|
29020
|
+
"type": "string"
|
|
29021
|
+
},
|
|
29022
|
+
{
|
|
29023
|
+
"type": "undefined"
|
|
29024
|
+
}
|
|
29025
|
+
],
|
|
29026
|
+
"optional": true,
|
|
29027
|
+
"required": false,
|
|
29028
|
+
"getter": false,
|
|
29029
|
+
"setter": false
|
|
29030
|
+
},
|
|
28755
29031
|
{
|
|
28756
29032
|
"name": "sortable",
|
|
28757
29033
|
"type": "boolean | undefined",
|
|
@@ -28780,7 +29056,29 @@
|
|
|
28780
29056
|
}
|
|
28781
29057
|
],
|
|
28782
29058
|
"methods": [],
|
|
28783
|
-
"events": [
|
|
29059
|
+
"events": [
|
|
29060
|
+
{
|
|
29061
|
+
"event": "mdsTableHeaderCellSort",
|
|
29062
|
+
"detail": "MdsTableHeaderCellSortEventDetail",
|
|
29063
|
+
"bubbles": true,
|
|
29064
|
+
"complexType": {
|
|
29065
|
+
"original": "MdsTableHeaderCellSortEventDetail",
|
|
29066
|
+
"resolved": "MdsTableHeaderCellSortEventDetail",
|
|
29067
|
+
"references": {
|
|
29068
|
+
"MdsTableHeaderCellSortEventDetail": {
|
|
29069
|
+
"location": "import",
|
|
29070
|
+
"path": "./meta/event-detail",
|
|
29071
|
+
"id": "src/components/mds-table-header-cell/meta/event-detail.ts::MdsTableHeaderCellSortEventDetail",
|
|
29072
|
+
"referenceLocation": "MdsTableHeaderCellSortEventDetail"
|
|
29073
|
+
}
|
|
29074
|
+
}
|
|
29075
|
+
},
|
|
29076
|
+
"cancelable": true,
|
|
29077
|
+
"composed": true,
|
|
29078
|
+
"docs": "Emits when the user changes the sort direction of the column, at every step of the cycle. With\n`sorting=\"external\"` on the table the rows are not moved: the application renders them in the\norder asked.",
|
|
29079
|
+
"docsTags": []
|
|
29080
|
+
}
|
|
29081
|
+
],
|
|
28784
29082
|
"listeners": [],
|
|
28785
29083
|
"styles": [],
|
|
28786
29084
|
"slots": [],
|
|
@@ -29073,7 +29371,7 @@
|
|
|
29073
29371
|
}
|
|
29074
29372
|
],
|
|
29075
29373
|
"usage": {
|
|
29076
|
-
"1. Description": "The `<mds-text>` web component is the foundational typography primitive of the Magma Design System. It decouples the _semantic typography role_ of a piece of text from the _HTML element_ that renders it, replacing raw heading, paragraph, label and inline tags (`<h1>`-`<h6>`, `<p>`, `<span>`, `<label>`, `<code>`, ...) with a single design-tokenized text node that is consumed internally by nearly every other Magma component.\n\n#### Semantic Behavior\n\n- **Typography drives the rendered tag**: when `tag` is left unset, a sensible default element is resolved from the chosen `typography` (e.g. `typography=\"h2\"` -> `<h2>`, `paragraph`/`detail` -> `<p>`, `label`/`option` -> `<label>`, `snippet`/`hack` -> `<code>`, `tip` -> `<div>`). Setting `tag` explicitly overrides this.\n- **Semantics vs. visual style are independent**: `typography` controls the visual ramp and the default element, but you may pin any allowed `tag` to keep the correct document outline (accessibility) while choosing a different visual scale.\n- **Text source is slot or prop**: text is normally provided through the default slot. Passing the `text` prop renders that string instead of the slotted content - required for the animation path, since the animation watches the `text` value.\n- **Default-slot is text only**: the default slot is intended for a plain text string; HTML elements or other components should not be slotted in.\n- **Animated reveal**: with `animation=\"yugop\"` the component runs a randomized character \"decode\" reveal whenever the `text` prop changes after load (the initial value is rendered as is); `animation=\"none\"` (the default) skips all animation.\n- **Animation tuning via CSS**: the yugop reveal reads `--mds-text-animation-speed` and `--mds-text-animation-placeholder-char`, so speed and placeholder glyph are themeable through CSS custom properties rather than props.\n\n#### Properties & Visual Configurations\n\n- **`typography`** selects the semantic text role from the shared typography ramp (titles `h1`-`h6` and `action`; informational `detail`, `paragraph`, `caption`, `label`, `option`, `tip`; monospaced `snippet`, `hack`). It is the primary prop and also determines the default rendered tag. Defaults to `'detail'`.\n- **`variant`** refines the _tone of a typography role_ and is specific to this component - it is the typography variation (`'title'`, `'info'`, `'read'`, `'code'`), not the shared component tone/variant ladder. Only `'read'` has a visual effect, and only on `paragraph`, `detail` and `caption` (it switches them to the reading family); the other values change nothing, and leaving it unset uses the role's default styling.\n- **`tag`** is an escape hatch to force a specific HTML element independently of `typography`, e.g. rendering a visually large heading as a `<span>` or marking text as `<strong>`/`<em>`/`<mark>` without changing the visual scale.\n- **`truncate`** governs overflow clipping: `'word'` forces single-line truncation (no wrapping), `'all'` clamps to a multi-line block whose line count is controlled by `--mds-text-line-clamp`, and `'none'` lets text flow normally.\n",
|
|
29374
|
+
"1. Description": "The `<mds-text>` web component is the foundational typography primitive of the Magma Design System. It decouples the _semantic typography role_ of a piece of text from the _HTML element_ that renders it, replacing raw heading, paragraph, label and inline tags (`<h1>`-`<h6>`, `<p>`, `<span>`, `<label>`, `<code>`, ...) with a single design-tokenized text node that is consumed internally by nearly every other Magma component.\n\n#### Semantic Behavior\n\n- **Typography drives the rendered tag**: when `tag` is left unset, a sensible default element is resolved from the chosen `typography` (e.g. `typography=\"h2\"` -> `<h2>`, `paragraph`/`detail` -> `<p>`, `label`/`option` -> `<label>`, `snippet`/`hack` -> `<code>`, `tip` -> `<div>`). Setting `tag` explicitly overrides this.\n- **Semantics vs. visual style are independent**: `typography` controls the visual ramp and the default element, but you may pin any allowed `tag` to keep the correct document outline (accessibility) while choosing a different visual scale.\n- **Text source is slot or prop**: text is normally provided through the default slot. Passing the `text` prop renders that string instead of the slotted content - required for the animation path, since the animation watches the `text` value.\n- **Default-slot is text only**: the default slot is intended for a plain text string; HTML elements or other components should not be slotted in.\n- **Animated reveal**: with `animation=\"yugop\"` the component runs a randomized character \"decode\" reveal whenever the `text` prop changes after load (the initial value is rendered as is); `animation=\"none\"` (the default) skips all animation. The revealed string is always painted as text, never parsed as HTML.\n- **Animation tuning via CSS**: the yugop reveal reads `--mds-text-animation-speed` and `--mds-text-animation-placeholder-char`, so speed and placeholder glyph are themeable through CSS custom properties rather than props. They are read each time a reveal starts, so a value changed after load applies to the next reveal. The placeholder is one character (a longer string keeps its first one); a speed that is not a positive number, or an empty placeholder, falls back to the defaults (`0.5` and a space).\n\n#### Properties & Visual Configurations\n\n- **`typography`** selects the semantic text role from the shared typography ramp (titles `h1`-`h6` and `action`; informational `detail`, `paragraph`, `caption`, `label`, `option`, `tip`; monospaced `snippet`, `hack`). It is the primary prop and also determines the default rendered tag. Defaults to `'detail'`.\n- **`variant`** refines the _tone of a typography role_ and is specific to this component - it is the typography variation (`'title'`, `'info'`, `'read'`, `'code'`), not the shared component tone/variant ladder. Only `'read'` has a visual effect, and only on `paragraph`, `detail` and `caption` (it switches them to the reading family); the other values change nothing, and leaving it unset uses the role's default styling.\n- **`tag`** is an escape hatch to force a specific HTML element independently of `typography`, e.g. rendering a visually large heading as a `<span>` or marking text as `<strong>`/`<em>`/`<mark>` without changing the visual scale.\n- **`truncate`** governs overflow clipping: `'word'` forces single-line truncation (no wrapping), `'all'` clamps to a multi-line block whose line count is controlled by `--mds-text-line-clamp`, and `'none'` lets text flow normally.\n",
|
|
29077
29375
|
"2. Pattern": "Correct and idiomatic ways to use the `<mds-text>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the typography ramp documented in [`agents/typography.md`](../../../../agents/typography.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Body Text via Default Slot\n\nThe canonical form for body copy. Slot a plain text string; `typography` defaults to `'detail'`, which renders a `<p>` element with the detail style.\n\n```html\n<mds-text>Inserisci il testo del messaggio nel campo sottostante.</mds-text>\n```\n\n#### Choosing a Typography Role\n\nSet `typography` to match the semantic role. The component resolves the correct HTML element automatically - `h1`-`h6` emit heading elements, `paragraph`/`detail` emit `<p>`, `label`/`option` emit `<label>`, `snippet`/`hack` emit `<code>`, `tip` and `action` emit `<div>` and `<span>` respectively.\n\n```html\n<mds-text typography=\"h1\">Benvenuto nel portale</mds-text>\n<mds-text typography=\"h2\">Impostazioni account</mds-text>\n<mds-text typography=\"paragraph\">Questo e' il corpo principale della pagina.</mds-text>\n<mds-text typography=\"caption\">Nota: i campi obbligatori sono contrassegnati con *</mds-text>\n<mds-text typography=\"label\">Nome utente</mds-text>\n<mds-text typography=\"tip\">Usa almeno 8 caratteri</mds-text>\n```\n\n#### Text via `text` Prop\n\nUse the `text` prop when the string comes from a JavaScript expression or data binding. This is also required for the `yugop` animation (see below) since the animation watches the prop value.\n\n```html\n<mds-text typography=\"detail\" text=\"Ultimo accesso: 3 giugno 2026\"></mds-text>\n```\n\n#### Reading Variant\n\nApply `variant=\"read\"` to `paragraph`, `detail`, or `caption` when rendering long-form editorial content. The reading variant keeps the same sizes but switches to the serif reading font (lighter for `paragraph` and `detail`), optimized for sustained reading.\n\n```html\n<mds-text typography=\"paragraph\" variant=\"read\">\n Il regolamento definisce le modalita' di accesso ai servizi digitali\n dell'amministrazione pubblica, in conformita' con le vigenti normative europee.\n</mds-text>\n\n<mds-text typography=\"detail\" variant=\"read\">\n Fonte: Gazzetta Ufficiale, serie generale n. 128 del 4 giugno 2026.\n</mds-text>\n```\n\n#### Monospaced Code Styles\n\nUse `typography=\"snippet\"` for inline code values or short terminal output. Use `typography=\"hack\"` for a smaller monospaced size suited to code-dense interfaces.\n\n```html\n<mds-text typography=\"snippet\">SELECT * FROM utenti WHERE attivo = true;</mds-text>\n<mds-text typography=\"hack\">npm install @maggioli-design-system/magma</mds-text>\n```\n\n#### Overriding the Rendered Tag\n\n`tag` is an escape hatch to pin a specific HTML element when the `typography` default is semantically wrong - for example, rendering a visually large heading as a `<span>` for a non-heading context, or marking inline text as `<strong>` or `<em>` without changing the visual scale.\n\n```html\n<!-- Visually h2 scale but not a landmark heading -->\n<mds-text typography=\"h2\" tag=\"span\">Sezione in evidenza</mds-text>\n\n<!-- Emphasized inline detail without changing scale -->\n<mds-text typography=\"detail\" tag=\"strong\">Attenzione: questa operazione e' irreversibile.</mds-text>\n\n<!-- Marked text using caption scale -->\n<mds-text typography=\"caption\" tag=\"mark\">Modificato il 3 giugno 2026</mds-text>\n```\n\n#### Single-Line Truncation\n\nUse `truncate=\"word\"` to clamp text to a single line with an ellipsis when layout space is constrained, for example inside a table cell or card header.\n\n```html\n<div style=\"width: 200px;\">\n <mds-text typography=\"detail\" truncate=\"word\">\n Titolo molto lungo che supera la larghezza disponibile del contenitore\n </mds-text>\n</div>\n```\n\n#### Multi-Line Clamp\n\nUse `truncate=\"all\"` to clamp text to a fixed number of lines. Control the number of visible lines via `--mds-text-line-clamp` (default 3).\n\n```html\n<mds-text typography=\"paragraph\" truncate=\"all\" style=\"--mds-text-line-clamp: 2;\">\n Questo paragrafo mostra solo le prime due righe di testo, troncando il resto\n con i puntini di sospensione indipendentemente dai caratteri di confine.\n</mds-text>\n```\n\n#### Animated Character Reveal\n\nSet `animation=\"yugop\"` together with the `text` prop to run a randomized character-decode reveal each time `text` changes; the initial value is rendered without animation. Tune the speed via `--mds-text-animation-speed`.\n\n```html\n<mds-text\n typography=\"h3\"\n animation=\"yugop\"\n text=\"Benvenuto nel sistema\"\n style=\"--mds-text-animation-speed: 1;\"\n></mds-text>\n```\n\n#### Custom Text Selection Colors\n\nOverride the default selection highlight via `--mds-text-selection-background` and `--mds-text-selection-color`. Use Magma color tokens inside `rgb()` so dark mode keeps working.\n\n```css\n.articolo-in-evidenza mds-text {\n --mds-text-selection-background: rgb(var(--label-orange-09));\n --mds-text-selection-color: rgb(var(--label-orange-01));\n}\n```\n\n#### Custom Line-Clamp Count\n\nSet `--mds-text-line-clamp` on the component host (or a parent selector) to vary the clamp depth per context without duplicating attributes.\n\n```css\n.abstract mds-text {\n --mds-text-line-clamp: 4;\n}\n\n.anteprima mds-text {\n --mds-text-line-clamp: 2;\n}\n```\n",
|
|
29078
29376
|
"3. Antipattern": "Common incorrect uses of `<mds-text>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Slot HTML Elements in the Default Slot\n\nThe default slot accepts plain text strings only. HTML elements or components slotted inside are outside the supported API: they keep their own browser and page styles instead of following the typography role.\n\n```html\n<!-- INCORRECT -->\n<mds-text typography=\"paragraph\">\n <strong>Attenzione:</strong> questa operazione e' <em>irreversibile</em>.\n</mds-text>\n\n<!-- CORRECT -->\n<mds-text typography=\"paragraph\">Attenzione: questa operazione e' irreversibile.</mds-text>\n<mds-text typography=\"paragraph\" tag=\"strong\">Attenzione:</mds-text>\n```\n\n#### Do Not Mix `text` Prop and Slotted Content\n\nWhen `text` is set, the component renders that string and ignores the slot entirely. Do not provide both - the slotted content is silently discarded.\n\n```html\n<!-- INCORRECT -->\n<mds-text text=\"Titolo dal prop\">Titolo dallo slot</mds-text>\n\n<!-- CORRECT -->\n<!-- Use either the prop (preferred for dynamic / animated content) -->\n<mds-text text=\"Titolo dal prop\"></mds-text>\n<!-- or the slot (convenient for static markup) -->\n<mds-text>Titolo dallo slot</mds-text>\n```\n\n#### Do Not Use `animation=\"yugop\"` Without the `text` Prop\n\nThe yugop animation requires the `text` prop because it watches prop changes to retrigger. Slotted content is not observed; changing it will not re-run the animation.\n\n```html\n<!-- INCORRECT -->\n<mds-text animation=\"yugop\">Testo animato dallo slot</mds-text>\n\n<!-- CORRECT -->\n<mds-text animation=\"yugop\" text=\"Testo animato dal prop\"></mds-text>\n```\n\n#### Do Not Apply an Invalid `variant` for the Chosen `typography`\n\n`variant` is specific to the typography role: only `paragraph`, `detail`, and `caption` accept `variant=\"read\"`. Applying `variant=\"read\"` to heading or label roles silently has no visual effect and adds misleading markup.\n\n```html\n<!-- INCORRECT -->\n<mds-text typography=\"h2\" variant=\"read\">Impostazioni</mds-text>\n<mds-text typography=\"label\" variant=\"read\">Nome</mds-text>\n\n<!-- CORRECT -->\n<mds-text typography=\"h2\">Impostazioni</mds-text>\n<mds-text typography=\"paragraph\" variant=\"read\">Testo editoriale lungo.</mds-text>\n```\n\n#### Do Not Use Raw HTML Headings Instead of `<mds-text>`\n\nReplace raw `<h1>`-`<h6>`, `<p>`, `<span>`, `<label>`, and `<code>` styled with generic utilities with `<mds-text>` in Magma-managed views (or apply the typography utilities of [`agents/typography.md`](../../../../agents/typography.md)). Generic sizes and weights bypass the design-token typography ramp, causing visual inconsistency across themes and sizes.\n\n```html\n<!-- INCORRECT -->\n<h2 class=\"text-2xl font-bold\">Riepilogo ordine</h2>\n<p class=\"text-sm text-fg-muted\">Totale: 128,00 EUR</p>\n\n<!-- CORRECT -->\n<mds-text typography=\"h2\">Riepilogo ordine</mds-text>\n<mds-text typography=\"caption\">Totale: 128,00 EUR</mds-text>\n```\n\n#### Do Not Reach Into Shadow DOM to Style Internal Elements\n\nThe component exposes five `--mds-text-*` CSS custom properties for customization. Do not pierce the shadow DOM via `::part()` or `>>>` selectors targeting the internal `.text` element - that implementation detail is not a documented part and may change.\n\n```css\n/* INCORRECT */\nmds-text >>> .text {\n letter-spacing: 0.1em;\n}\n\n/* CORRECT - set via host; the host styles cascade into the shadow text node */\nmds-text {\n letter-spacing: 0.1em;\n --mds-text-selection-background: rgb(var(--label-sky-09));\n}\n```\n\n#### Do Not Confuse `truncate=\"word\"` and `truncate=\"all\"`\n\n`truncate=\"word\"` forces **single-line** truncation. `truncate=\"all\"` enables **multi-line** clamping controlled by `--mds-text-line-clamp`. Using `\"word\"` when you want multi-line clamp will collapse the text to one line unexpectedly.\n\n```html\n<!-- INCORRECT - collapses to one line when two lines were intended -->\n<mds-text typography=\"paragraph\" truncate=\"word\" style=\"--mds-text-line-clamp: 2;\">\n Testo lungo che dovrebbe mostrare due righe prima del troncamento.\n</mds-text>\n\n<!-- CORRECT -->\n<mds-text typography=\"paragraph\" truncate=\"all\" style=\"--mds-text-line-clamp: 2;\">\n Testo lungo che dovrebbe mostrare due righe prima del troncamento.\n</mds-text>\n```\n"
|
|
29079
29377
|
},
|
|
@@ -30131,8 +30429,8 @@
|
|
|
30131
30429
|
"filePath": "src/components/mds-tooltip/mds-tooltip.tsx",
|
|
30132
30430
|
"encapsulation": "shadow",
|
|
30133
30431
|
"tag": "mds-tooltip",
|
|
30134
|
-
"readme": "# mds-tooltip\n\n
|
|
30135
|
-
"docs": "",
|
|
30432
|
+
"readme": "# mds-tooltip\n\n\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
|
|
30433
|
+
"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.",
|
|
30136
30434
|
"docsTags": [
|
|
30137
30435
|
{
|
|
30138
30436
|
"name": "slot",
|
|
@@ -30140,9 +30438,9 @@
|
|
|
30140
30438
|
}
|
|
30141
30439
|
],
|
|
30142
30440
|
"usage": {
|
|
30143
|
-
"1. Description": "The `<mds-tooltip>` web component is the floating contextual hint of the Magma Design System. It renders a small text bubble that attaches to a separate trigger element identified by a CSS selector, rather than relying on the native `title` attribute.\n\n#### Semantic Behavior\n\n- **Detached trigger model**: The tooltip is not wrapped around its trigger; the required `target` selector is resolved and the component binds itself to the first matching caller.\n- **Hover-driven visibility**: The bubble appears and disappears as the pointer enters and leaves the trigger; keyboard focus does not show it. The tooltip takes `role=\"tooltip\"` and, when it shares a DOM tree with the trigger, writes `aria-describedby` on it.\n- **Visibility is the source of truth**: Setting `visible` programmatically shows or dismisses the bubble, allowing the tooltip to be controlled without a hover.\n- **Live repositioning**: Changing any layout prop (`placement`, `offset`, `disableShift`, `shiftPadding`, `strategy`, `flip`, `disableAutoPlacement`) recomputes the floating position on the fly.\n- **Text-only default slot**: The default slot is meant for a plain text string (exposed as the `text` shadow part); HTML elements or components should not be slotted in.\n\n#### Properties & Visual Configurations\n\n- **`target`** (required) is the CSS selector of the trigger element the tooltip listens to and anchors against; the first match wins.\n- **`placement`** chooses the preferred side and alignment relative to the caller (e.g. `'top'`, `'bottom-start'`); the system picks the best side automatically by default (**`disableAutoPlacement`** opts out and pins to `placement`) and **`flip`** allows falling back to the opposite side when the preferred one lacks space (only together with `disableAutoPlacement`).\n- the bubble is kept inside the viewport by default (**`disableShift`** opts out), with **`shiftPadding`** reserving a safe gap from the viewport edges; **`offset`** sets the distance between the bubble and the caller.\n- **`strategy`** selects the CSS positioning strategy: `'fixed'` (default) escapes clipping ancestors, `'absolute'` anchors within the nearest positioned ancestor.\n- **`typography`** picks the text scale of the bubble (`'tip'`, `'caption'`, `'detail'`), where `'tip'` is the default compact hint sizing.\n",
|
|
30144
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-tooltip>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Tooltip on a Button\n\nThe most common form. Give the trigger element an `id` (or any unique CSS selector) and point `target` at it. The tooltip listens for hover events on the trigger and positions itself automatically.\n\n```html\n<mds-button id=\"salva-btn\" label=\"Salva documento\" variant=\"primary\" tone=\"strong\"></mds-button>\n<mds-tooltip target=\"#salva-btn\">Salva le modifiche correnti</mds-tooltip>\n```\n\n#### Tooltip on a Non-Interactive Element\n\n`target` accepts any CSS selector, not just `#id`. Use a class or attribute selector when the trigger is a static element such as a status icon.\n\n```html\n<mds-icon class=\"stato-icona\" name=\"mi/baseline/info\"></mds-icon>\n<mds-tooltip target=\".stato-icona\">Ultima sincronizzazione: oggi alle 08:30</mds-tooltip>\n```\n\n#### Placement and Preferred Side\n\nOverride the default `top` placement with `placement` when layout requires a different side. Auto placement is on by default and picks the side by itself, so `placement` takes effect only together with `disable-auto-placement`, which locks the side.\n\n```html\n<mds-button id=\"dettagli-btn\" label=\"Dettagli\" variant=\"primary\" tone=\"outline\"></mds-button>\n<mds-tooltip target=\"#dettagli-btn\" placement=\"right\" disable-auto-placement>\n Apre il pannello laterale con i dettagli completi\n</mds-tooltip>\n```\n\nAccepted values: `top`, `top-start`, `top-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`, `right`, `right-start`, `right-end`.\n\n#### Flip Fallback When Space is Tight\n\nEnable `flip` so the tooltip moves to the opposite side if the preferred placement collides with the viewport edge. It works only together with `disable-auto-placement`: it keeps a preferred side while allowing a single-axis fallback.\n\n```html\n<mds-button id=\"azione-btn\" label=\"Azione\" variant=\"primary\"></mds-button>\n<mds-tooltip target=\"#azione-btn\" placement=\"top\" disable-auto-placement flip>\n Esegui l'operazione selezionata\n</mds-tooltip>\n```\n\n#### Viewport-Safe Shift\n\nBy default the tooltip slides along its axis so it stays inside the viewport (set `disable-shift` to opt out). Increase `shift-padding` to keep a wider safe margin from the viewport edges.\n\n```html\n<mds-button id=\"bordo-btn\" label=\"Vicino al bordo\" variant=\"dark\" tone=\"outline\"></mds-button>\n<mds-tooltip target=\"#bordo-btn\" shift-padding=\"24\">\n Questa azione e' irreversibile\n</mds-tooltip>\n```\n\n#### Custom Offset Distance\n\nIncrease `offset` when additional breathing room between the trigger and the bubble is required - for example inside dense toolbars or on elements with large focus rings.\n\n```html\n<mds-button id=\"info-btn\" label=\"Info\" variant=\"info\" tone=\"weak\"></mds-button>\n<mds-tooltip target=\"#info-btn\" offset=\"20\">\n Informazioni aggiuntive sul campo\n</mds-tooltip>\n```\n\n#### Programmatic Visibility\n\nSet the `visible` attribute (or property) to control the tooltip without hover. Useful for guided tours, onboarding hints, or error annotations that appear on demand.\n\n```html\n<mds-button id=\"primo-accesso\" label=\"Inizia\" variant=\"primary\"></mds-button>\n<mds-tooltip id=\"hint\" target=\"#primo-accesso\" visible>\n Benvenuto! Clicca qui per iniziare la configurazione.\n</mds-tooltip>\n\n<script>\n const hint = document.querySelector('#hint');\n // Dismiss programmatically when the user acknowledges the hint\n document.querySelector('#primo-accesso').addEventListener('click', () => {\n hint.visible = false;\n });\n</script>\n```\n\n#### Typography Scale\n\n`typography` adjusts the text scale inside the bubble. Use `'tip'` (default) for compact hints, `'caption'` for slightly larger labels, and `'detail'` for the largest, body-size text.\n\n```html\n<!-- Default compact hint -->\n<mds-tooltip target=\"#campo-nome\" typography=\"tip\">Massimo 64 caratteri</mds-tooltip>\n\n<!-- Slightly larger label -->\n<mds-tooltip target=\"#campo-data\" typography=\"caption\">Formato: GG/MM/AAAA</mds-tooltip>\n```\n\n#### Positioning Strategy\n\nUse `strategy=\"absolute\"` when the tooltip must be contained within a scrolling ancestor instead of the viewport. The default `strategy=\"fixed\"` escapes any clipping or overflow-hidden parent.\n\n```html\n<!-- Inside a scrollable panel with overflow:hidden ancestors -->\n<mds-tooltip target=\"#voce-lista\" strategy=\"absolute\">Trascina per riordinare</mds-tooltip>\n```\n\n#### Styling Customization\n\nStyle the tooltip only through its documented `--mds-tooltip-*` CSS custom properties. Set them on the host element or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.onboarding-hint mds-tooltip {\n --mds-tooltip-background: rgb(var(--magma-accent-surface));\n --mds-tooltip-arrow-background: rgb(var(--magma-accent-surface));\n --mds-tooltip-delay: 0.25s;\n --mds-tooltip-duration: 0.3s;\n --mds-tooltip-z-index: 5000;\n}\n```\n",
|
|
30145
|
-
"3. Antipattern": "Common incorrect uses of `<mds-tooltip>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Bare ID String as `target`\n\nThe value of `target` is passed directly to `querySelector`, so a CSS selector is required: a bare id (`hint-trigger`) looks for an element named `<hint-trigger>`, finds nothing, and the tooltip never attaches.\n\n```html\n<!-- INCORRECT -->\n<span id=\"hint-trigger\">Aiuto</span>\n<mds-tooltip target=\"hint-trigger\">Testo di aiuto</mds-tooltip>\n\n<!-- CORRECT -->\n<span id=\"hint-trigger\">Aiuto</span>\n<mds-tooltip target=\"#hint-trigger\">Testo di aiuto</mds-tooltip>\n```\n\n#### Do Not Slot HTML Elements or Components\n\nThe default slot is text-only. Nesting HTML elements or Magma components breaks the inner layout and may produce unexpected rendering because the slot is wrapped in `<mds-text>`.\n\n```html\n<!-- INCORRECT -->\n<mds-tooltip target=\"#voce\">\n <mds-icon name=\"mi/baseline/warning\"></mds-icon>\n <strong>Attenzione:</strong> campo obbligatorio\n</mds-tooltip>\n\n<!-- CORRECT -->\n<mds-tooltip target=\"#voce\">Attenzione: campo obbligatorio</mds-tooltip>\n```\n\n#### Do Not Wrap the Trigger Inside the Tooltip\n\n`<mds-tooltip>` uses a detached trigger model - the tooltip is placed as a sibling in the DOM and linked via `target`, not wrapped around its trigger. Nesting the trigger breaks the floating position logic.\n\n```html\n<!-- INCORRECT -->\n<mds-tooltip target=\"#btn\">\n <mds-button id=\"btn\" label=\"Elimina\"></mds-button>\n Elimina il record selezionato\n</mds-tooltip>\n\n<!-- CORRECT -->\n<mds-button id=\"btn\" label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n<mds-tooltip target=\"#btn\">Elimina il record selezionato</mds-tooltip>\n```\n\n#### Do Not Set `visible=\"false\"` to Hide the Tooltip\n\n`visible` is a boolean attribute; setting it to the string `\"false\"` leaves the attribute on the element. The tooltip itself reads it as hidden, but every presence check (`[visible]`, `hasAttribute('visible')`) still reads it as visible. Remove the attribute (or set the property to `false`) to hide it.\n\n```html\n<!-- INCORRECT -->\n<mds-tooltip target=\"#campo\" visible=\"false\">Testo nascosto</mds-tooltip>\n\n<!-- CORRECT -->\n<mds-tooltip target=\"#campo\">Testo nascosto</mds-tooltip>\n```\n\n```js\n// CORRECT (programmatic)\ndocument.querySelector('mds-tooltip').visible = false;\n```\n\n#### Do Not Pierce the Shadow DOM to Style Internal Parts\n\nThe only supported customization surface is the set of `--mds-tooltip-*` CSS custom properties and the documented `text` shadow part. Targeting undocumented internal selectors couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-tooltip >>> .text {\n font-style: italic;\n}\nmds-tooltip::part(arrow) {\n fill: red;\n}\n\n/* CORRECT */\nmds-tooltip {\n --mds-tooltip-background: rgb(var(--magma-accent-surface));\n --mds-tooltip-delay: 0.5s;\n}\nmds-tooltip::part(text) {\n font-style: italic;\n}\n```\n\n#### Do Not Replace `<mds-tooltip>` with a Native `title` Attribute\n\nThe native `title` tooltip is not styleable and not announced consistently by screen readers on touch devices. Use `<mds-tooltip>` for all contextual hints.\n\n```html\n<!-- INCORRECT -->\n<mds-button label=\"Elimina\" title=\"Elimina il record selezionato\"></mds-button>\n\n<!-- CORRECT -->\n<mds-button id=\"elimina-btn\" label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n<mds-tooltip target=\"#elimina-btn\">Elimina il record selezionato</mds-tooltip>\n```\n"
|
|
30441
|
+
"1. Description": "The `<mds-tooltip>` web component is the floating contextual hint of the Magma Design System. It renders a small text bubble that attaches to a separate trigger element identified by a CSS selector, rather than relying on the native `title` attribute.\n\n#### Semantic Behavior\n\n- **Detached trigger model**: The tooltip is not wrapped around its trigger; the required `target` selector is resolved and the component binds itself to the first matching caller.\n- **Hover-driven visibility**: The bubble appears and disappears as the pointer enters and leaves the trigger; keyboard focus does not show it. The tooltip takes `role=\"tooltip\"` and, when it shares a DOM tree with the trigger, writes `aria-describedby` on it, or `aria-labelledby` with `relation=\"label\"`; an attribute the trigger already has is left alone.\n- **Visibility is the source of truth**: Setting `visible` programmatically shows or dismisses the bubble, allowing the tooltip to be controlled without a hover.\n- **Live repositioning**: Changing any layout prop (`placement`, `offset`, `disableShift`, `shiftPadding`, `strategy`, `flip`, `disableAutoPlacement`) recomputes the floating position on the fly.\n- **Text-only default slot**: The default slot is meant for a plain text string (exposed as the `text` shadow part); HTML elements or components should not be slotted in.\n\n#### Properties & Visual Configurations\n\n- **`target`** (required) is the CSS selector of the trigger element the tooltip listens to and anchors against; the first match wins.\n- **`placement`** chooses the preferred side and alignment relative to the caller (e.g. `'top'`, `'bottom-start'`); the system picks the best side automatically by default (**`disableAutoPlacement`** opts out and pins to `placement`) and **`flip`** allows falling back to the opposite side when the preferred one lacks space (only together with `disableAutoPlacement`).\n- the bubble is kept inside the viewport by default (**`disableShift`** opts out), with **`shiftPadding`** reserving a safe gap from the viewport edges; **`offset`** sets the distance between the bubble and the caller.\n- **`strategy`** selects the CSS positioning strategy: `'fixed'` (default) escapes clipping ancestors, `'absolute'` anchors within the nearest positioned ancestor.\n- **`relation`** says what the tooltip is to its trigger: its `'description'` (default, `aria-describedby`), or its `'label'` (`aria-labelledby`), when the tooltip text is the only visible name of the trigger, as on an icon-only button. Changing it moves the attribute on the trigger.\n- **`typography`** picks the text scale of the bubble (`'tip'`, `'caption'`, `'detail'`), where `'tip'` is the default compact hint sizing.\n",
|
|
30442
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-tooltip>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Tooltip on a Button\n\nThe most common form. Give the trigger element an `id` (or any unique CSS selector) and point `target` at it. The tooltip listens for hover events on the trigger and positions itself automatically.\n\n```html\n<mds-button id=\"salva-btn\" label=\"Salva documento\" variant=\"primary\" tone=\"strong\"></mds-button>\n<mds-tooltip target=\"#salva-btn\">Salva le modifiche correnti</mds-tooltip>\n```\n\n#### Naming an Icon-Only Button\n\nOn an icon-only button the tooltip usually shows the name of the button. Set `relation=\"label\"` so that the tooltip is the name (`aria-labelledby`) and not a description: the button needs no `aria-label`, and a screen reader does not read the same text twice. Use it only on an interactive trigger, a button or a link: ARIA does not allow a name on a generic element.\n\n```html\n<mds-button id=\"tokens-btn\" icon=\"mi/baseline/palette\" variant=\"dark\" tone=\"text\"></mds-button>\n<mds-tooltip target=\"#tokens-btn\" relation=\"label\">Tokens</mds-tooltip>\n```\n\n#### Tooltip on a Non-Interactive Element\n\n`target` accepts any CSS selector, not just `#id`. Use a class or attribute selector when the trigger is a static element such as a status icon.\n\n```html\n<mds-icon class=\"stato-icona\" name=\"mi/baseline/info\"></mds-icon>\n<mds-tooltip target=\".stato-icona\">Ultima sincronizzazione: oggi alle 08:30</mds-tooltip>\n```\n\n#### Placement and Preferred Side\n\nOverride the default `top` placement with `placement` when layout requires a different side. Auto placement is on by default and picks the side by itself, so `placement` takes effect only together with `disable-auto-placement`, which locks the side.\n\n```html\n<mds-button id=\"dettagli-btn\" label=\"Dettagli\" variant=\"primary\" tone=\"outline\"></mds-button>\n<mds-tooltip target=\"#dettagli-btn\" placement=\"right\" disable-auto-placement>\n Apre il pannello laterale con i dettagli completi\n</mds-tooltip>\n```\n\nAccepted values: `top`, `top-start`, `top-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`, `right`, `right-start`, `right-end`.\n\n#### Flip Fallback When Space is Tight\n\nEnable `flip` so the tooltip moves to the opposite side if the preferred placement collides with the viewport edge. It works only together with `disable-auto-placement`: it keeps a preferred side while allowing a single-axis fallback.\n\n```html\n<mds-button id=\"azione-btn\" label=\"Azione\" variant=\"primary\"></mds-button>\n<mds-tooltip target=\"#azione-btn\" placement=\"top\" disable-auto-placement flip>\n Esegui l'operazione selezionata\n</mds-tooltip>\n```\n\n#### Viewport-Safe Shift\n\nBy default the tooltip slides along its axis so it stays inside the viewport (set `disable-shift` to opt out). Increase `shift-padding` to keep a wider safe margin from the viewport edges.\n\n```html\n<mds-button id=\"bordo-btn\" label=\"Vicino al bordo\" variant=\"dark\" tone=\"outline\"></mds-button>\n<mds-tooltip target=\"#bordo-btn\" shift-padding=\"24\">\n Questa azione e' irreversibile\n</mds-tooltip>\n```\n\n#### Custom Offset Distance\n\nIncrease `offset` when additional breathing room between the trigger and the bubble is required - for example inside dense toolbars or on elements with large focus rings.\n\n```html\n<mds-button id=\"info-btn\" label=\"Info\" variant=\"info\" tone=\"weak\"></mds-button>\n<mds-tooltip target=\"#info-btn\" offset=\"20\">\n Informazioni aggiuntive sul campo\n</mds-tooltip>\n```\n\n#### Programmatic Visibility\n\nSet the `visible` attribute (or property) to control the tooltip without hover. Useful for guided tours, onboarding hints, or error annotations that appear on demand.\n\n```html\n<mds-button id=\"primo-accesso\" label=\"Inizia\" variant=\"primary\"></mds-button>\n<mds-tooltip id=\"hint\" target=\"#primo-accesso\" visible>\n Benvenuto! Clicca qui per iniziare la configurazione.\n</mds-tooltip>\n\n<script>\n const hint = document.querySelector('#hint');\n // Dismiss programmatically when the user acknowledges the hint\n document.querySelector('#primo-accesso').addEventListener('click', () => {\n hint.visible = false;\n });\n</script>\n```\n\n#### Typography Scale\n\n`typography` adjusts the text scale inside the bubble. Use `'tip'` (default) for compact hints, `'caption'` for slightly larger labels, and `'detail'` for the largest, body-size text.\n\n```html\n<!-- Default compact hint -->\n<mds-tooltip target=\"#campo-nome\" typography=\"tip\">Massimo 64 caratteri</mds-tooltip>\n\n<!-- Slightly larger label -->\n<mds-tooltip target=\"#campo-data\" typography=\"caption\">Formato: GG/MM/AAAA</mds-tooltip>\n```\n\n#### Positioning Strategy\n\nUse `strategy=\"absolute\"` when the tooltip must be contained within a scrolling ancestor instead of the viewport. The default `strategy=\"fixed\"` escapes any clipping or overflow-hidden parent.\n\n```html\n<!-- Inside a scrollable panel with overflow:hidden ancestors -->\n<mds-tooltip target=\"#voce-lista\" strategy=\"absolute\">Trascina per riordinare</mds-tooltip>\n```\n\n#### Styling Customization\n\nStyle the tooltip only through its documented `--mds-tooltip-*` CSS custom properties. Set them on the host element or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.onboarding-hint mds-tooltip {\n --mds-tooltip-background: rgb(var(--magma-accent-surface));\n --mds-tooltip-arrow-background: rgb(var(--magma-accent-surface));\n --mds-tooltip-delay: 0.25s;\n --mds-tooltip-duration: 0.3s;\n --mds-tooltip-z-index: 5000;\n}\n```\n",
|
|
30443
|
+
"3. Antipattern": "Common incorrect uses of `<mds-tooltip>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Bare ID String as `target`\n\nThe value of `target` is passed directly to `querySelector`, so a CSS selector is required: a bare id (`hint-trigger`) looks for an element named `<hint-trigger>`, finds nothing, and the tooltip never attaches.\n\n```html\n<!-- INCORRECT -->\n<span id=\"hint-trigger\">Aiuto</span>\n<mds-tooltip target=\"hint-trigger\">Testo di aiuto</mds-tooltip>\n\n<!-- CORRECT -->\n<span id=\"hint-trigger\">Aiuto</span>\n<mds-tooltip target=\"#hint-trigger\">Testo di aiuto</mds-tooltip>\n```\n\n#### Do Not Slot HTML Elements or Components\n\nThe default slot is text-only. Nesting HTML elements or Magma components breaks the inner layout and may produce unexpected rendering because the slot is wrapped in `<mds-text>`.\n\n```html\n<!-- INCORRECT -->\n<mds-tooltip target=\"#voce\">\n <mds-icon name=\"mi/baseline/warning\"></mds-icon>\n <strong>Attenzione:</strong> campo obbligatorio\n</mds-tooltip>\n\n<!-- CORRECT -->\n<mds-tooltip target=\"#voce\">Attenzione: campo obbligatorio</mds-tooltip>\n```\n\n#### Do Not Wrap the Trigger Inside the Tooltip\n\n`<mds-tooltip>` uses a detached trigger model - the tooltip is placed as a sibling in the DOM and linked via `target`, not wrapped around its trigger. Nesting the trigger breaks the floating position logic.\n\n```html\n<!-- INCORRECT -->\n<mds-tooltip target=\"#btn\">\n <mds-button id=\"btn\" label=\"Elimina\"></mds-button>\n Elimina il record selezionato\n</mds-tooltip>\n\n<!-- CORRECT -->\n<mds-button id=\"btn\" label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n<mds-tooltip target=\"#btn\">Elimina il record selezionato</mds-tooltip>\n```\n\n#### Do Not Set `visible=\"false\"` to Hide the Tooltip\n\n`visible` is a boolean attribute; setting it to the string `\"false\"` leaves the attribute on the element. The tooltip itself reads it as hidden, but every presence check (`[visible]`, `hasAttribute('visible')`) still reads it as visible. Remove the attribute (or set the property to `false`) to hide it.\n\n```html\n<!-- INCORRECT -->\n<mds-tooltip target=\"#campo\" visible=\"false\">Testo nascosto</mds-tooltip>\n\n<!-- CORRECT -->\n<mds-tooltip target=\"#campo\">Testo nascosto</mds-tooltip>\n```\n\n```js\n// CORRECT (programmatic)\ndocument.querySelector('mds-tooltip').visible = false;\n```\n\n#### Do Not Pierce the Shadow DOM to Style Internal Parts\n\nThe only supported customization surface is the set of `--mds-tooltip-*` CSS custom properties and the documented `text` shadow part. Targeting undocumented internal selectors couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-tooltip >>> .text {\n font-style: italic;\n}\nmds-tooltip::part(arrow) {\n fill: red;\n}\n\n/* CORRECT */\nmds-tooltip {\n --mds-tooltip-background: rgb(var(--magma-accent-surface));\n --mds-tooltip-delay: 0.5s;\n}\nmds-tooltip::part(text) {\n font-style: italic;\n}\n```\n\n#### Do Not Repeat the Name of the Trigger as Its Description\n\nA tooltip describes its trigger by default. When its text is the name of the trigger, as on an icon-only button, an `aria-label` with the same text makes a screen reader read it twice, as the name and as the description. Make the tooltip the name instead.\n\n```html\n<!-- INCORRECT -->\n<mds-button id=\"tokens-btn\" icon=\"mi/baseline/palette\" aria-label=\"Tokens\"></mds-button>\n<mds-tooltip target=\"#tokens-btn\">Tokens</mds-tooltip>\n\n<!-- CORRECT -->\n<mds-button id=\"tokens-btn\" icon=\"mi/baseline/palette\"></mds-button>\n<mds-tooltip target=\"#tokens-btn\" relation=\"label\">Tokens</mds-tooltip>\n```\n\n#### Do Not Replace `<mds-tooltip>` with a Native `title` Attribute\n\nThe native `title` tooltip is not styleable and not announced consistently by screen readers on touch devices. Use `<mds-tooltip>` for all contextual hints.\n\n```html\n<!-- INCORRECT -->\n<mds-button label=\"Elimina\" title=\"Elimina il record selezionato\"></mds-button>\n\n<!-- CORRECT -->\n<mds-button id=\"elimina-btn\" label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n<mds-tooltip target=\"#elimina-btn\">Elimina il record selezionato</mds-tooltip>\n```\n"
|
|
30146
30444
|
},
|
|
30147
30445
|
"props": [
|
|
30148
30446
|
{
|
|
@@ -30342,6 +30640,47 @@
|
|
|
30342
30640
|
"getter": false,
|
|
30343
30641
|
"setter": false
|
|
30344
30642
|
},
|
|
30643
|
+
{
|
|
30644
|
+
"name": "relation",
|
|
30645
|
+
"type": "\"description\" | \"label\"",
|
|
30646
|
+
"complexType": {
|
|
30647
|
+
"original": "FloatingUIRelation",
|
|
30648
|
+
"resolved": "\"description\" | \"label\"",
|
|
30649
|
+
"references": {
|
|
30650
|
+
"FloatingUIRelation": {
|
|
30651
|
+
"location": "import",
|
|
30652
|
+
"path": "@type/floating-ui",
|
|
30653
|
+
"id": "src/type/floating-ui.ts::FloatingUIRelation",
|
|
30654
|
+
"referenceLocation": "FloatingUIRelation"
|
|
30655
|
+
}
|
|
30656
|
+
}
|
|
30657
|
+
},
|
|
30658
|
+
"mutable": false,
|
|
30659
|
+
"attr": "relation",
|
|
30660
|
+
"reflectToAttr": true,
|
|
30661
|
+
"docs": "Sets what the tooltip is to its caller: its `description` (`aria-describedby`), or its\n`label` (`aria-labelledby`), when the tooltip holds the only visible name of the caller, as on\nan icon-only button.",
|
|
30662
|
+
"docsTags": [
|
|
30663
|
+
{
|
|
30664
|
+
"name": "default",
|
|
30665
|
+
"text": "'description'"
|
|
30666
|
+
}
|
|
30667
|
+
],
|
|
30668
|
+
"default": "'description'",
|
|
30669
|
+
"values": [
|
|
30670
|
+
{
|
|
30671
|
+
"value": "description",
|
|
30672
|
+
"type": "string"
|
|
30673
|
+
},
|
|
30674
|
+
{
|
|
30675
|
+
"value": "label",
|
|
30676
|
+
"type": "string"
|
|
30677
|
+
}
|
|
30678
|
+
],
|
|
30679
|
+
"optional": false,
|
|
30680
|
+
"required": false,
|
|
30681
|
+
"getter": false,
|
|
30682
|
+
"setter": false
|
|
30683
|
+
},
|
|
30345
30684
|
{
|
|
30346
30685
|
"name": "shiftPadding",
|
|
30347
30686
|
"type": "number",
|
|
@@ -31914,9 +32253,9 @@
|
|
|
31914
32253
|
}
|
|
31915
32254
|
],
|
|
31916
32255
|
"usage": {
|
|
31917
|
-
"1. Description": "The `<mds-usage>` web component is a documentation-oriented annotation block of the Magma Design System used to frame example content as a recommendation, a warning, or an informational note. It wraps slotted content in a labelled, status-colored container and has no native HTML primitive equivalent - it is a presentational guidance device, typically used inside design-system docs and Storybook.\n\n#### Semantic Behavior\n\n- **Status semantics via `variant`**: The chosen `variant` drives the border and header color from the shared status palette (success / info / error / warning), so the container reads as the matching guidance category.\n- **Content role mapping**: The content region conveys an allowed-vs-disallowed nature to assistive technology - insertion for the `'do'` and `'info'` variants, deletion for `'dont'` and `'warn'`.\n- **Localized header label**: When `alias` is not provided, the header text is resolved from the bundled locale dictionary (el / en / es / it) keyed by `variant`, so the label follows the document language.\n- **Default slot is content**: The default (unnamed) slot accepts a text string, HTML elements, or other components - it is the body of the usage block, not the label.\n\n#### Properties & Visual Configurations\n\n`variant` is the primary configuration prop. Unlike most Magma components, this is NOT the shared variant/tone ladder defined in [`agents/variants.md`](../../../../agents/variants.md); it is a component-specific guidance category:\n\n- **`variant=\"do\"`**: marks recommended / allowed usage (success styling, insertion role).\n- **`variant=\"dont\"`**: marks discouraged / disallowed usage (error styling, deletion role).\n- **`variant=\"info\"`**: neutral informational note (info styling, insertion role); this is the default.\n- **`variant=\"warn\"`**: cautionary note (warning styling, deletion role).\n\n#### Other behavioral props\n\n- **`alias`** overrides the auto-generated, localized header phrase with a custom string when the default category label is not specific enough for the example being shown.\n",
|
|
31918
|
-
"2. Pattern": "Correct and idiomatic ways to use the `<mds-usage>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Default Informational Note\n\nThe simplest form. Omit `variant` to get the `info` default - a neutral, blue-tinted container that draws attention to a usage note without implying correctness or incorrectness.\n\n```html\n<mds-usage>\n <mds-text>\n Utilizzare sempre il colore primario del tema per le azioni principali.\n </mds-text>\n</mds-usage>\n```\n\n#### Recommended Pattern (`variant=\"do\"`)\n\nUse `variant=\"do\"` to mark a component usage or design pattern as explicitly recommended. The container adopts success styling and the content region carries `role=\"insertion\"` for assistive technology.\n\n```html\n<mds-usage variant=\"do\">\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n</mds-usage>\n```\n\n#### Discouraged Pattern (`variant=\"dont\"`)\n\nUse `variant=\"dont\"` to mark a usage as explicitly forbidden or inadvisable. The container adopts error styling and the content region carries `role=\"deletion\"`.\n\n```html\n<mds-usage variant=\"dont\">\n <button style=\"background: blue; color: white;\">Salva</button>\n</mds-usage>\n```\n\n#### Cautionary Note (`variant=\"warn\"`)\n\nUse `variant=\"warn\"` when a pattern is not forbidden but requires care - for example when a prop combination is valid but has side effects, or when a rare edge case exists. The container adopts warning styling and carries `role=\"deletion\"`.\n\n```html\n<mds-usage variant=\"warn\">\n <mds-text>\n Impostare type=\"button\" su ogni pulsante all'interno di un form\n per evitare invii accidentali.\n </mds-text>\n</mds-usage>\n```\n\n#### Custom Header Label via `alias`\n\nWhen the auto-generated, localized header (\"Consentito\", \"Non consentito\", etc.) is not specific enough for the context, pass `alias` to replace it with a custom string. The locale dictionary is bypassed entirely.\n\n```html\n<mds-usage variant=\"do\" alias=\"Struttura consigliata\">\n <mds-text>Usare mds-card con header, content e footer separati.</mds-text>\n</mds-usage>\n\n<mds-usage variant=\"dont\" alias=\"Struttura da evitare\">\n <mds-text>Non annidare mds-card all'interno di un'altra mds-card.</mds-text>\n</mds-usage>\n```\n\n#### Side-by-Side Do / Dont Pair\n\nPair a `do` block with a `dont` block to illustrate a correct and an incorrect approach in the same documentation section. No extra wrapper is needed - use a CSS grid or flex container.\n\n```html\n<div style=\"display: grid; grid-template-columns: 1fr 1fr; gap: 1rem;\">\n <mds-usage variant=\"do\">\n <mds-button label=\"Conferma\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-usage>\n\n <mds-usage variant=\"dont\">\n <mds-button label=\"Conferma\" tone=\"strong\" style=\"--mds-button-background: green;\"></mds-button>\n </mds-usage>\n</div>\n```\n\n#### Rich Slotted Content\n\nThe default slot accepts any HTML or Magma components. Use this to annotate a fully composed UI fragment rather than a single element.\n\n```html\n<mds-usage variant=\"do\" alias=\"Composizione corretta di mds-card\">\n <mds-card>\n <mds-card-header slot=\"header\">\n <mds-text typography=\"h5\">Titolo scheda</mds-text>\n </mds-card-header>\n <mds-card-content slot=\"content\">\n <mds-text>Contenuto principale della scheda.</mds-text>\n </mds-card-content>\n <mds-card-footer slot=\"footer\">\n <mds-button label=\"Azione\" variant=\"primary\"></mds-button>\n </mds-card-footer>\n </mds-card>\n</mds-usage>\n```\n\n#### CSS Custom Property Overrides\n\nCustomize the container appearance through the three documented `--mds-usage-*` CSS custom properties. Set them on the host or a parent selector and use the semantic color roles via `rgb(var(--magma-<role>))` to keep dark mode working.\n\n```css\n.docs-callout mds-usage {\n --mds-usage-border-color: rgb(var(--magma-accent-ai-border));\n --mds-usage-header-background: rgb(var(--magma-accent-ai-emphasis));\n --mds-usage-header-color: rgb(var(--magma-accent-ai-on-emphasis));\n}\n```\n",
|
|
31919
|
-
"3. Antipattern": "Common incorrect uses of `<mds-usage>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Use `variant` as the Shared Tone/Variant Ladder\n\n`<mds-usage>` does not use the system-wide `variant` ladder (`primary`, `secondary`, `error`, etc.). Its `variant` prop is component-specific (`do`, `dont`, `info`, `warn`). Passing a system variant silently falls back to the base info-like styling, with an empty header label (the locale has no entry for it).\n\n```html\n<!-- INCORRECT -->\n<mds-usage variant=\"error\">\n <mds-text>Non consentito.</mds-text>\n</mds-usage>\n\n<!-- CORRECT -->\n<mds-usage variant=\"dont\">\n <mds-text>Non consentito.</mds-text>\n</mds-usage>\n```\n\n#### Do Not Omit the Slot Content\n\n`<mds-usage>` renders a labeled container; without slotted content the block displays only the colored header strip with no body - producing a visually broken annotation. Always provide meaningful content in the default slot.\n\n```html\n<!-- INCORRECT -->\n<mds-usage variant=\"do\"></mds-usage>\n\n<!-- CORRECT -->\n<mds-usage variant=\"do\">\n <mds-text>Usare sempre il colore del tema per i pulsanti primari.</mds-text>\n</mds-usage>\n```\n\n#### Do Not Put the Label in the Default Slot\n\nThe default slot is the body of the block. Placing a heading or label string there makes it look like body text, not a header. Use the `alias` prop to supply a custom header label.\n\n```html\n<!-- INCORRECT -->\n<mds-usage variant=\"do\">\n Struttura consigliata\n</mds-usage>\n\n<!-- CORRECT -->\n<mds-usage variant=\"do\" alias=\"Struttura consigliata\">\n <mds-text>Comporre mds-card con i suoi sotto-componenti dedicati.</mds-text>\n</mds-usage>\n```\n\n#### Do Not Pierce the Shadow DOM to Restyle the Header\n\n`::part(header)`, `::part(icon)`, and `::part(label)` are the only documented extension points for shadow internals. Targeting undocumented class names or using `>>>` couples code to implementation details that may change. For color overrides, use the documented `--mds-usage-*` CSS custom properties instead.\n\n```css\n/* INCORRECT */\nmds-usage >>> .header {\n background: rgb(var(--magma-accent-ai-emphasis));\n}\n\n/* CORRECT */\nmds-usage {\n --mds-usage-header-background: rgb(var(--magma-accent-ai-emphasis));\n --mds-usage-header-color: rgb(var(--magma-accent-ai-on-emphasis));\n}\n```\n\n#### Do Not Use `<mds-usage>` as a General-Purpose Card\n\n`<mds-usage>` is a documentation/Storybook annotation primitive - it is not a card, callout, or alert for production UIs. For in-app status messages use [`mds-banner`](../mds-banner/AGENTS.md), [`mds-note`](../mds-note/AGENTS.md), or [`mds-toast`](../mds-toast/AGENTS.md).\n\n```html\n<!-- INCORRECT - using mds-usage as a production alert -->\n<mds-usage variant=\"warn\">\n <mds-text>La sessione sta per scadere.</mds-text>\n</mds-usage>\n\n<!-- CORRECT - use the appropriate production component -->\n<mds-banner variant=\"warning\" tone=\"weak\">La sessione sta per scadere.</mds-banner>\n```\n"
|
|
32256
|
+
"1. Description": "The `<mds-usage>` web component is a documentation-oriented annotation block of the Magma Design System used to frame example content as a recommendation, a warning, or an informational note. It wraps slotted content in a labelled, status-colored container and has no native HTML primitive equivalent - it is a presentational guidance device, typically used inside design-system docs and Storybook.\n\n#### Semantic Behavior\n\n- **Status semantics via `variant`**: The chosen `variant` drives the border and header color from the shared status palette (success / info / error / warning) and the header icon (a tick for `do`, an X for `dont`, an info sign for `info`, a warning triangle for `warn`), so the container reads as the matching guidance category even without its color.\n- **Content role mapping**: The content region conveys an allowed-vs-disallowed nature to assistive technology - insertion for the `'do'` and `'info'` variants, deletion for `'dont'` and `'warn'`.\n- **Localized header label**: When `alias` is not provided, the header text is resolved from the bundled locale dictionary (el / en / es / it) keyed by `variant`, so the label follows the document language.\n- **Default slot is content**: The default (unnamed) slot accepts a text string, HTML elements, or other components - it is the body of the usage block, not the label.\n\n#### Properties & Visual Configurations\n\n`variant` is the primary configuration prop. Unlike most Magma components, this is NOT the shared variant/tone ladder defined in [`agents/variants.md`](../../../../agents/variants.md); it is a component-specific guidance category:\n\n- **`variant=\"do\"`**: marks recommended / allowed usage (success styling, insertion role).\n- **`variant=\"dont\"`**: marks discouraged / disallowed usage (error styling, deletion role).\n- **`variant=\"info\"`**: neutral informational note (info styling, insertion role); this is the default.\n- **`variant=\"warn\"`**: cautionary note (warning styling, deletion role).\n\n#### Other behavioral props\n\n- **`alias`** overrides the auto-generated, localized header phrase with a custom string when the default category label is not specific enough for the example being shown.\n- **`icon`** replaces the header icon of the `variant` with any icon slug; colors, label and content role still follow the `variant`. When not set or empty, the icon follows the `variant`. The header icon is decorative: the label carries the meaning.\n",
|
|
32257
|
+
"2. Pattern": "Correct and idiomatic ways to use the `<mds-usage>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Default Informational Note\n\nThe simplest form. Omit `variant` to get the `info` default - a neutral, blue-tinted container that draws attention to a usage note without implying correctness or incorrectness.\n\n```html\n<mds-usage>\n <mds-text>\n Utilizzare sempre il colore primario del tema per le azioni principali.\n </mds-text>\n</mds-usage>\n```\n\n#### Recommended Pattern (`variant=\"do\"`)\n\nUse `variant=\"do\"` to mark a component usage or design pattern as explicitly recommended. The container adopts success styling and the content region carries `role=\"insertion\"` for assistive technology.\n\n```html\n<mds-usage variant=\"do\">\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n</mds-usage>\n```\n\n#### Discouraged Pattern (`variant=\"dont\"`)\n\nUse `variant=\"dont\"` to mark a usage as explicitly forbidden or inadvisable. The container adopts error styling and the content region carries `role=\"deletion\"`.\n\n```html\n<mds-usage variant=\"dont\">\n <button style=\"background: blue; color: white;\">Salva</button>\n</mds-usage>\n```\n\n#### Cautionary Note (`variant=\"warn\"`)\n\nUse `variant=\"warn\"` when a pattern is not forbidden but requires care - for example when a prop combination is valid but has side effects, or when a rare edge case exists. The container adopts warning styling and carries `role=\"deletion\"`.\n\n```html\n<mds-usage variant=\"warn\">\n <mds-text>\n Impostare type=\"button\" su ogni pulsante all'interno di un form\n per evitare invii accidentali.\n </mds-text>\n</mds-usage>\n```\n\n#### Custom Header Label via `alias`\n\nWhen the auto-generated, localized header (\"Consentito\", \"Non consentito\", etc.) is not specific enough for the context, pass `alias` to replace it with a custom string. The locale dictionary is bypassed entirely.\n\n```html\n<mds-usage variant=\"do\" alias=\"Struttura consigliata\">\n <mds-text>Usare mds-card con header, content e footer separati.</mds-text>\n</mds-usage>\n\n<mds-usage variant=\"dont\" alias=\"Struttura da evitare\">\n <mds-text>Non annidare mds-card all'interno di un'altra mds-card.</mds-text>\n</mds-usage>\n```\n\n#### Custom Header Icon via `icon`\n\nEach `variant` has its own header icon. When a custom `alias` names a more specific category, pass `icon` with a slug that illustrates it; the `variant` still drives the colors, the label fallback and the content role. Keep the icon coherent with the `variant`.\n\n```html\n<mds-usage variant=\"do\" alias=\"Struttura consigliata\" icon=\"mi/baseline/account-tree\">\n <mds-text>Usare mds-card con header, content e footer separati.</mds-text>\n</mds-usage>\n```\n\n#### Side-by-Side Do / Dont Pair\n\nPair a `do` block with a `dont` block to illustrate a correct and an incorrect approach in the same documentation section. No extra wrapper is needed - use a CSS grid or flex container.\n\n```html\n<div style=\"display: grid; grid-template-columns: 1fr 1fr; gap: 1rem;\">\n <mds-usage variant=\"do\">\n <mds-button label=\"Conferma\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-usage>\n\n <mds-usage variant=\"dont\">\n <mds-button label=\"Conferma\" tone=\"strong\" style=\"--mds-button-background: green;\"></mds-button>\n </mds-usage>\n</div>\n```\n\n#### Rich Slotted Content\n\nThe default slot accepts any HTML or Magma components. Use this to annotate a fully composed UI fragment rather than a single element.\n\n```html\n<mds-usage variant=\"do\" alias=\"Composizione corretta di mds-card\">\n <mds-card>\n <mds-card-header slot=\"header\">\n <mds-text typography=\"h5\">Titolo scheda</mds-text>\n </mds-card-header>\n <mds-card-content slot=\"content\">\n <mds-text>Contenuto principale della scheda.</mds-text>\n </mds-card-content>\n <mds-card-footer slot=\"footer\">\n <mds-button label=\"Azione\" variant=\"primary\"></mds-button>\n </mds-card-footer>\n </mds-card>\n</mds-usage>\n```\n\n#### CSS Custom Property Overrides\n\nCustomize the container appearance through the three documented `--mds-usage-*` CSS custom properties. Set them on the host or a parent selector and use the semantic color roles via `rgb(var(--magma-<role>))` to keep dark mode working.\n\n```css\n.docs-callout mds-usage {\n --mds-usage-border-color: rgb(var(--magma-accent-ai-border));\n --mds-usage-header-background: rgb(var(--magma-accent-ai-emphasis));\n --mds-usage-header-color: rgb(var(--magma-accent-ai-on-emphasis));\n}\n```\n",
|
|
32258
|
+
"3. Antipattern": "Common incorrect uses of `<mds-usage>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/anti-patterns.md`](../../../../agents/anti-patterns.md) - they apply here too but are not repeated.\n\n#### Do Not Use `variant` as the Shared Tone/Variant Ladder\n\n`<mds-usage>` does not use the system-wide `variant` ladder (`primary`, `secondary`, `error`, etc.). Its `variant` prop is component-specific (`do`, `dont`, `info`, `warn`). Passing a system variant silently falls back to the base info-like styling and the info icon, with an empty header label (the locale has no entry for it).\n\n```html\n<!-- INCORRECT -->\n<mds-usage variant=\"error\">\n <mds-text>Non consentito.</mds-text>\n</mds-usage>\n\n<!-- CORRECT -->\n<mds-usage variant=\"dont\">\n <mds-text>Non consentito.</mds-text>\n</mds-usage>\n```\n\n#### Do Not Use an `icon` That Contradicts the `variant`\n\n`icon` replaces only the glyph: colors, label and content role still follow the `variant`. An icon that means the opposite (a tick on a `dont` block, a cross on a `do` block) sends two conflicting signals. To change the meaning, change the `variant`; use `icon` only to make the same meaning more specific.\n\n```html\n<!-- INCORRECT -->\n<mds-usage variant=\"dont\" icon=\"mi/baseline/check-circle\">\n <mds-text>Non annidare mds-card all'interno di un'altra mds-card.</mds-text>\n</mds-usage>\n\n<!-- CORRECT -->\n<mds-usage variant=\"dont\">\n <mds-text>Non annidare mds-card all'interno di un'altra mds-card.</mds-text>\n</mds-usage>\n```\n\n#### Do Not Omit the Slot Content\n\n`<mds-usage>` renders a labeled container; without slotted content the block displays only the colored header strip with no body - producing a visually broken annotation. Always provide meaningful content in the default slot.\n\n```html\n<!-- INCORRECT -->\n<mds-usage variant=\"do\"></mds-usage>\n\n<!-- CORRECT -->\n<mds-usage variant=\"do\">\n <mds-text>Usare sempre il colore del tema per i pulsanti primari.</mds-text>\n</mds-usage>\n```\n\n#### Do Not Put the Label in the Default Slot\n\nThe default slot is the body of the block. Placing a heading or label string there makes it look like body text, not a header. Use the `alias` prop to supply a custom header label.\n\n```html\n<!-- INCORRECT -->\n<mds-usage variant=\"do\">\n Struttura consigliata\n</mds-usage>\n\n<!-- CORRECT -->\n<mds-usage variant=\"do\" alias=\"Struttura consigliata\">\n <mds-text>Comporre mds-card con i suoi sotto-componenti dedicati.</mds-text>\n</mds-usage>\n```\n\n#### Do Not Pierce the Shadow DOM to Restyle the Header\n\n`::part(header)`, `::part(icon)`, and `::part(label)` are the only documented extension points for shadow internals. Targeting undocumented class names or using `>>>` couples code to implementation details that may change. For color overrides, use the documented `--mds-usage-*` CSS custom properties instead.\n\n```css\n/* INCORRECT */\nmds-usage >>> .header {\n background: rgb(var(--magma-accent-ai-emphasis));\n}\n\n/* CORRECT */\nmds-usage {\n --mds-usage-header-background: rgb(var(--magma-accent-ai-emphasis));\n --mds-usage-header-color: rgb(var(--magma-accent-ai-on-emphasis));\n}\n```\n\n#### Do Not Use `<mds-usage>` as a General-Purpose Card\n\n`<mds-usage>` is a documentation/Storybook annotation primitive - it is not a card, callout, or alert for production UIs. For in-app status messages use [`mds-banner`](../mds-banner/AGENTS.md), [`mds-note`](../mds-note/AGENTS.md), or [`mds-toast`](../mds-toast/AGENTS.md).\n\n```html\n<!-- INCORRECT - using mds-usage as a production alert -->\n<mds-usage variant=\"warn\">\n <mds-text>La sessione sta per scadere.</mds-text>\n</mds-usage>\n\n<!-- CORRECT - use the appropriate production component -->\n<mds-banner variant=\"warning\" tone=\"weak\">La sessione sta per scadere.</mds-banner>\n```\n"
|
|
31920
32259
|
},
|
|
31921
32260
|
"props": [
|
|
31922
32261
|
{
|
|
@@ -31945,6 +32284,32 @@
|
|
|
31945
32284
|
"getter": false,
|
|
31946
32285
|
"setter": false
|
|
31947
32286
|
},
|
|
32287
|
+
{
|
|
32288
|
+
"name": "icon",
|
|
32289
|
+
"type": "string | undefined",
|
|
32290
|
+
"complexType": {
|
|
32291
|
+
"original": "string",
|
|
32292
|
+
"resolved": "string | undefined",
|
|
32293
|
+
"references": {}
|
|
32294
|
+
},
|
|
32295
|
+
"mutable": false,
|
|
32296
|
+
"attr": "icon",
|
|
32297
|
+
"reflectToAttr": false,
|
|
32298
|
+
"docs": "Specifies the icon displayed in the header; when not set or empty, the icon follows the `variant`",
|
|
32299
|
+
"docsTags": [],
|
|
32300
|
+
"values": [
|
|
32301
|
+
{
|
|
32302
|
+
"type": "string"
|
|
32303
|
+
},
|
|
32304
|
+
{
|
|
32305
|
+
"type": "undefined"
|
|
32306
|
+
}
|
|
32307
|
+
],
|
|
32308
|
+
"optional": true,
|
|
32309
|
+
"required": false,
|
|
32310
|
+
"getter": false,
|
|
32311
|
+
"setter": false
|
|
32312
|
+
},
|
|
31948
32313
|
{
|
|
31949
32314
|
"name": "variant",
|
|
31950
32315
|
"type": "\"do\" | \"dont\" | \"info\" | \"warn\"",
|
|
@@ -31963,7 +32328,7 @@
|
|
|
31963
32328
|
"mutable": false,
|
|
31964
32329
|
"attr": "variant",
|
|
31965
32330
|
"reflectToAttr": false,
|
|
31966
|
-
"docs": "Specifies the
|
|
32331
|
+
"docs": "Specifies the guidance category of the content, which drives colors, header label and icon",
|
|
31967
32332
|
"docsTags": [
|
|
31968
32333
|
{
|
|
31969
32334
|
"name": "default",
|
|
@@ -32430,6 +32795,11 @@
|
|
|
32430
32795
|
}
|
|
32431
32796
|
],
|
|
32432
32797
|
"typeLibrary": {
|
|
32798
|
+
"src/type/input.ts::InputSizeType": {
|
|
32799
|
+
"declaration": "\"sm\" | \"md\" | \"lg\"",
|
|
32800
|
+
"docstring": "",
|
|
32801
|
+
"path": "src/type/input.ts"
|
|
32802
|
+
},
|
|
32433
32803
|
"src/components/mds-input-date-range/mds-input-date-range.tsx::EventDate": {
|
|
32434
32804
|
"declaration": "export interface EventDate {\n caller: HTMLMdsInputDateRangePreselectionElement;\n start: string;\n end?: string;\n}",
|
|
32435
32805
|
"docstring": "",
|
|
@@ -33060,6 +33430,11 @@
|
|
|
33060
33430
|
"docstring": "",
|
|
33061
33431
|
"path": "src/components/mds-tab-item/meta/event-detail.ts"
|
|
33062
33432
|
},
|
|
33433
|
+
"src/components/mds-table/meta/type.ts::MdsTableSortingType": {
|
|
33434
|
+
"declaration": "export type MdsTableSortingType = 'internal' | 'external';",
|
|
33435
|
+
"docstring": "",
|
|
33436
|
+
"path": "src/components/mds-table/meta/type.ts"
|
|
33437
|
+
},
|
|
33063
33438
|
"src/components/mds-table/meta/event-detail.ts::MdsTableSelectionEventDetail": {
|
|
33064
33439
|
"declaration": "export interface MdsTableSelectionEventDetail {\n rows: MdsTableRowSelection[];\n}",
|
|
33065
33440
|
"docstring": "",
|
|
@@ -33075,6 +33450,11 @@
|
|
|
33075
33450
|
"docstring": "",
|
|
33076
33451
|
"path": "src/components/mds-table-header-cell/meta/types.ts"
|
|
33077
33452
|
},
|
|
33453
|
+
"src/components/mds-table-header-cell/meta/event-detail.ts::MdsTableHeaderCellSortEventDetail": {
|
|
33454
|
+
"declaration": "export interface MdsTableHeaderCellSortEventDetail {\n direction: SortDirectionType;\n index: number;\n sortKey?: string;\n}",
|
|
33455
|
+
"docstring": "",
|
|
33456
|
+
"path": "src/components/mds-table-header-cell/meta/event-detail.ts"
|
|
33457
|
+
},
|
|
33078
33458
|
"src/type/text.ts::TypographyTagType": {
|
|
33079
33459
|
"declaration": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | \"label\" | \"code\" | \"strong\" | \"abbr\" | \"address\" | \"article\" | \"b\" | \"bdo\" | \"blockquote\" | \"cite\" | \"dd\" | \"del\" | \"details\" | \"dfn\" | \"div\" | \"dl\" | \"dt\" | \"em\" | \"figcaption\" | \"i\" | \"ins\" | \"kbd\" | \"legend\" | \"li\" | \"mark\" | \"ol\" | \"p\" | \"pre\" | \"q\" | \"rb\" | \"rt\" | \"ruby\" | \"s\" | \"samp\" | \"small\" | \"span\" | \"sub\" | \"summary\" | \"sup\" | \"time\" | \"u\" | \"ul\" | \"var\"",
|
|
33080
33460
|
"docstring": "",
|
|
@@ -33085,6 +33465,11 @@
|
|
|
33085
33465
|
"docstring": "",
|
|
33086
33466
|
"path": "src/components/mds-toast/meta/types.ts"
|
|
33087
33467
|
},
|
|
33468
|
+
"src/type/floating-ui.ts::FloatingUIRelation": {
|
|
33469
|
+
"declaration": "\"label\" | \"description\"",
|
|
33470
|
+
"docstring": "",
|
|
33471
|
+
"path": "src/type/floating-ui.ts"
|
|
33472
|
+
},
|
|
33088
33473
|
"src/type/tree.ts::TreeAppearance": {
|
|
33089
33474
|
"declaration": "\"none\" | \"depth\"",
|
|
33090
33475
|
"docstring": "",
|