@maggioli-design-system/magma 2.12.0 → 2.13.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +1 -1
- package/CHANGELOG.md +72 -0
- package/README.md +6 -5
- package/agents/assets.md +7 -6
- package/agents/color.md +7 -4
- package/agents/components.md +3 -2
- package/agents/conventions.md +11 -1
- package/agents/install.md +10 -3
- package/agents/patterns/actions.md +7 -6
- package/agents/patterns/empty-state.md +5 -7
- package/agents/patterns/previews/actions/banner.dark.webp +0 -0
- package/agents/patterns/previews/actions/banner.light.webp +0 -0
- package/agents/patterns/previews/actions/confirm.dark.webp +0 -0
- package/agents/patterns/previews/actions/confirm.light.webp +0 -0
- package/agents/patterns/previews/actions/danger-zone.dark.webp +0 -0
- package/agents/patterns/previews/actions/danger-zone.light.webp +0 -0
- package/agents/patterns/previews/actions/dismiss-message.light.webp +0 -0
- package/agents/patterns/previews/actions/dismiss.dark.webp +0 -0
- package/agents/patterns/previews/actions/dismiss.light.webp +0 -0
- package/agents/patterns/previews/actions/part-primary.light.webp +0 -0
- package/agents/patterns/previews/actions/stacked.light.webp +0 -0
- package/agents/patterns/previews/app-shell/back-office.light.webp +0 -0
- package/agents/patterns/previews/app-shell/many-sections.dark.webp +0 -0
- package/agents/patterns/previews/app-shell/many-sections.light.webp +0 -0
- package/agents/patterns/previews/app-shell/public-service.dark.webp +0 -0
- package/agents/patterns/previews/app-shell/public-service.light.webp +0 -0
- package/agents/patterns/previews/app-shell/section-menus.dark.webp +0 -0
- package/agents/patterns/previews/app-shell/section-menus.light.webp +0 -0
- package/agents/patterns/previews/confirm-action/ask-before-sending.dark.webp +0 -0
- package/agents/patterns/previews/confirm-action/ask-before-sending.light.webp +0 -0
- package/agents/patterns/previews/confirm-action/ask-first-many.dark.webp +0 -0
- package/agents/patterns/previews/confirm-action/ask-first-many.light.webp +0 -0
- package/agents/patterns/previews/confirm-action/ask-first.dark.webp +0 -0
- package/agents/patterns/previews/confirm-action/ask-first.light.webp +0 -0
- package/agents/patterns/previews/confirm-action/make-reversible.dark.webp +0 -0
- package/agents/patterns/previews/confirm-action/make-reversible.light.webp +0 -0
- package/agents/patterns/previews/confirm-action/send-as-shown.dark.webp +0 -0
- package/agents/patterns/previews/confirm-action/send-as-shown.light.webp +0 -0
- package/agents/patterns/previews/empty-state/add-the-first.dark.webp +0 -0
- package/agents/patterns/previews/empty-state/add-the-first.html +5 -7
- package/agents/patterns/previews/empty-state/add-the-first.light.webp +0 -0
- package/agents/patterns/previews/empty-state/all-done.dark.webp +0 -0
- package/agents/patterns/previews/empty-state/all-done.html +5 -7
- package/agents/patterns/previews/empty-state/all-done.light.webp +0 -0
- package/agents/patterns/previews/empty-state/clear-filters.dark.webp +0 -0
- package/agents/patterns/previews/empty-state/clear-filters.html +4 -6
- package/agents/patterns/previews/empty-state/clear-filters.light.webp +0 -0
- package/agents/patterns/previews/empty-state/filled-by-others.dark.webp +0 -0
- package/agents/patterns/previews/empty-state/filled-by-others.html +5 -7
- package/agents/patterns/previews/empty-state/filled-by-others.light.webp +0 -0
- package/agents/patterns/previews/empty-state/not-found.dark.webp +0 -0
- package/agents/patterns/previews/empty-state/not-found.html +5 -7
- package/agents/patterns/previews/empty-state/not-found.light.webp +0 -0
- package/agents/patterns/previews/error-recovery/changed-meanwhile.dark.webp +0 -0
- package/agents/patterns/previews/error-recovery/changed-meanwhile.light.webp +0 -0
- package/agents/patterns/previews/error-recovery/check-or-repeat.light.webp +0 -0
- package/agents/patterns/previews/error-recovery/content-another-way.light.webp +0 -0
- package/agents/patterns/previews/error-recovery/partial.dark.webp +0 -0
- package/agents/patterns/previews/error-recovery/partial.light.webp +0 -0
- package/agents/patterns/previews/error-recovery/retry-action.light.webp +0 -0
- package/agents/patterns/previews/error-recovery/retry-content.dark.webp +0 -0
- package/agents/patterns/previews/error-recovery/sign-in-again.dark.webp +0 -0
- package/agents/patterns/previews/error-recovery/sign-in-again.light.webp +0 -0
- package/agents/patterns/previews/item-list/documents-of-a-request.dark.webp +0 -0
- package/agents/patterns/previews/item-list/documents-of-a-request.light.webp +0 -0
- package/agents/patterns/previews/item-list/queue-of-a-desk.dark.webp +0 -0
- package/agents/patterns/previews/item-list/queue-of-a-desk.html +1 -1
- package/agents/patterns/previews/item-list/queue-of-a-desk.light.webp +0 -0
- package/agents/patterns/previews/item-list/requests-of-an-office.dark.webp +0 -0
- package/agents/patterns/previews/item-list/requests-of-an-office.light.webp +0 -0
- package/agents/patterns/previews/item-list/requests-to-assign.dark.webp +0 -0
- package/agents/patterns/previews/item-list/requests-to-assign.html +3 -12
- package/agents/patterns/previews/item-list/requests-to-assign.light.webp +0 -0
- package/agents/patterns/previews/labels-and-values/payment-before-paying.dark.webp +0 -0
- package/agents/patterns/previews/labels-and-values/what-is-sent.dark.webp +0 -0
- package/agents/patterns/previews/labels-and-values/what-is-sent.light.webp +0 -0
- package/agents/patterns/previews/list-with-filters/act-on-many.dark.webp +0 -0
- package/agents/patterns/previews/list-with-filters/act-on-many.html +2 -9
- package/agents/patterns/previews/list-with-filters/act-on-many.light.webp +0 -0
- package/agents/patterns/previews/list-with-filters/find-and-open.light.webp +0 -0
- package/agents/patterns/previews/list-with-filters/show-new-items.dark.webp +0 -0
- package/agents/patterns/previews/list-with-filters/show-new-items.html +1 -1
- package/agents/patterns/previews/list-with-filters/show-new-items.light.webp +0 -0
- package/agents/patterns/previews/loading/await-and-say.dark.webp +0 -0
- package/agents/patterns/previews/loading/await-and-say.html +2 -5
- package/agents/patterns/previews/loading/first-load.dark.webp +0 -0
- package/agents/patterns/previews/loading/first-load.light.webp +0 -0
- package/agents/patterns/previews/loading/keep-while-reloading.dark.webp +0 -0
- package/agents/patterns/previews/loading/long-load-measured.dark.webp +0 -0
- package/agents/patterns/previews/loading/long-load-measured.light.webp +0 -0
- package/agents/patterns/previews/loading/long-load.dark.webp +0 -0
- package/agents/patterns/previews/loading/long-load.light.webp +0 -0
- package/agents/patterns/previews/loading/progress-in-place.light.webp +0 -0
- package/agents/patterns/previews/message-placement/action-done-elsewhere.dark.webp +0 -0
- package/agents/patterns/previews/message-placement/action-done-elsewhere.light.webp +0 -0
- package/agents/patterns/previews/message-placement/action-failed-elsewhere.dark.webp +0 -0
- package/agents/patterns/previews/message-placement/action-failed-in-place.dark.webp +0 -0
- package/agents/patterns/previews/message-placement/action-failed-in-place.light.webp +0 -0
- package/agents/patterns/previews/message-placement/action-partial-in-place.dark.webp +0 -0
- package/agents/patterns/previews/message-placement/action-partial-in-place.light.webp +0 -0
- package/agents/patterns/previews/message-placement/app-deadline.dark.webp +0 -0
- package/agents/patterns/previews/message-placement/app-deadline.light.webp +0 -0
- package/agents/patterns/previews/message-placement/app-failed.light.webp +0 -0
- package/agents/patterns/previews/message-placement/decision.dark.webp +0 -0
- package/agents/patterns/previews/message-placement/decision.light.webp +0 -0
- package/agents/patterns/previews/message-placement/field-error.dark.webp +0 -0
- package/agents/patterns/previews/message-placement/field-error.light.webp +0 -0
- package/agents/patterns/previews/message-placement/field-hint.light.webp +0 -0
- package/agents/patterns/previews/message-placement/field-valid.dark.webp +0 -0
- package/agents/patterns/previews/message-placement/field-valid.light.webp +0 -0
- package/agents/patterns/previews/message-placement/region-failed.dark.webp +0 -0
- package/agents/patterns/previews/message-placement/region-info.dark.webp +0 -0
- package/agents/patterns/previews/message-placement/region-info.light.webp +0 -0
- package/agents/patterns/previews/page-header/contact-being-edited.dark.webp +0 -0
- package/agents/patterns/previews/page-header/contact-being-edited.light.webp +0 -0
- package/agents/patterns/previews/page-header/members-of-a-group.light.webp +0 -0
- package/agents/patterns/previews/page-header/request-from-the-list.dark.webp +0 -0
- package/agents/patterns/previews/record-detail/ask-for-words.dark.webp +0 -0
- package/agents/patterns/previews/record-detail/ask-for-words.light.webp +0 -0
- package/agents/patterns/previews/record-detail/edit-data.light.webp +0 -0
- package/agents/patterns/previews/record-detail/read-the-data.dark.webp +0 -0
- package/agents/patterns/previews/record-detail/read-the-data.light.webp +0 -0
- package/agents/patterns/previews/record-detail/record-changed.dark.webp +0 -0
- package/agents/patterns/previews/record-detail/record-changed.light.webp +0 -0
- package/agents/patterns/previews/record-detail/run-at-once.dark.webp +0 -0
- package/agents/patterns/previews/record-detail/run-at-once.light.webp +0 -0
- package/agents/patterns/previews/record-detail/work-on-it.dark.webp +0 -0
- package/agents/patterns/previews/record-detail/work-on-it.light.webp +0 -0
- package/agents/patterns/previews/rhythm/between-containers.dark.webp +0 -0
- package/agents/patterns/previews/rhythm/between-containers.light.webp +0 -0
- package/agents/patterns/previews/rhythm/between-fields.dark.webp +0 -0
- package/agents/patterns/previews/rhythm/between-fields.light.webp +0 -0
- package/agents/patterns/previews/rhythm/between-groups.light.webp +0 -0
- package/agents/patterns/previews/rhythm/between-sections.dark.webp +0 -0
- package/agents/patterns/previews/rhythm/between-sections.light.webp +0 -0
- package/agents/patterns/previews/rhythm/inline.light.webp +0 -0
- package/agents/patterns/previews/rhythm/inset.dark.webp +0 -0
- package/agents/patterns/previews/rhythm/inset.light.webp +0 -0
- package/agents/patterns/previews/rhythm/title-content.dark.webp +0 -0
- package/agents/patterns/previews/rhythm/title-content.light.webp +0 -0
- package/agents/patterns/previews/surfaces/band.dark.webp +0 -0
- package/agents/patterns/previews/surfaces/band.light.webp +0 -0
- package/agents/patterns/previews/surfaces/canvas.dark.webp +0 -0
- package/agents/patterns/previews/surfaces/canvas.light.webp +0 -0
- package/agents/patterns/previews/surfaces/card.dark.webp +0 -0
- package/agents/patterns/previews/surfaces/card.light.webp +0 -0
- package/agents/patterns/previews/surfaces/dialog.dark.webp +0 -0
- package/agents/patterns/previews/surfaces/dialog.light.webp +0 -0
- package/agents/patterns/previews/surfaces/edit-actions.dark.webp +0 -0
- package/agents/patterns/previews/surfaces/edit-actions.light.webp +0 -0
- package/agents/patterns/previews/surfaces/intro-band.dark.webp +0 -0
- package/agents/patterns/previews/surfaces/intro-band.html +66 -0
- package/agents/patterns/previews/surfaces/intro-band.light.webp +0 -0
- package/agents/patterns/previews/surfaces/section.dark.webp +0 -0
- package/agents/patterns/previews/surfaces/section.light.webp +0 -0
- package/agents/patterns/previews/titles/dialog.dark.webp +0 -0
- package/agents/patterns/previews/titles/dialog.light.webp +0 -0
- package/agents/patterns/previews/titles/group.light.webp +0 -0
- package/agents/patterns/previews/titles/page.light.webp +0 -0
- package/agents/patterns/previews/titles/part.light.webp +0 -0
- package/agents/patterns/previews/titles/section.light.webp +0 -0
- package/agents/patterns/previews/widths/dialog.dark.webp +0 -0
- package/agents/patterns/previews/widths/dialog.light.webp +0 -0
- package/agents/patterns/previews/widths/field.dark.webp +0 -0
- package/agents/patterns/previews/widths/field.light.webp +0 -0
- package/agents/patterns/previews/widths/form.dark.webp +0 -0
- package/agents/patterns/previews/widths/form.light.webp +0 -0
- package/agents/patterns/previews/widths/page.dark.webp +0 -0
- package/agents/patterns/previews/widths/page.light.webp +0 -0
- package/agents/patterns/previews/widths/reading.dark.webp +0 -0
- package/agents/patterns/previews/widths/reading.light.webp +0 -0
- package/agents/patterns/surfaces.md +49 -11
- package/agents/patterns/titles.md +15 -14
- package/agents/patterns.md +1 -1
- package/agents/theming.md +5 -0
- package/dist/cjs/{floating-controller-B4YhrWm8.js → floating-controller-B21tqid0.js} +51 -4
- package/dist/cjs/{floating-ui.dom-VQ_HnnRe.js → floating-ui.dom-1Z4VE-PH.js} +1 -0
- package/dist/cjs/{index-BQNHYWJg.js → index-B99V_UhC.js} +87 -44
- package/dist/cjs/{index-Csgx951d.js → index-CFEj7WVH.js} +12 -1
- package/dist/cjs/index.cjs.js +45 -3
- package/dist/cjs/loader.cjs.js +2 -2
- package/dist/cjs/{locale-DgMC52AD.js → locale-6jikg4jE.js} +1 -1
- package/dist/cjs/magma-components.cjs.js +3 -3
- package/dist/cjs/mds-accordion-item.cjs.entry.js +10 -7
- package/dist/cjs/mds-accordion-timer-item.cjs.entry.js +10 -7
- package/dist/cjs/mds-accordion-timer.cjs.entry.js +4 -3
- package/dist/cjs/mds-accordion.cjs.entry.js +5 -4
- package/dist/cjs/mds-author.cjs.entry.js +4 -3
- package/dist/cjs/mds-avatar-stack-item.cjs.entry.js +4 -3
- package/dist/cjs/mds-avatar-stack.cjs.entry.js +4 -3
- package/dist/cjs/mds-avatar.cjs.entry.js +5 -4
- package/dist/cjs/mds-badge.cjs.entry.js +5 -4
- package/dist/cjs/mds-banner_3.cjs.entry.js +56 -27
- package/dist/cjs/mds-benchmark-bar.cjs.entry.js +4 -3
- package/dist/cjs/mds-bibliography.cjs.entry.js +4 -3
- package/dist/cjs/mds-book.cjs.entry.js +8 -7
- package/dist/cjs/mds-breadcrumb-item.cjs.entry.js +4 -3
- package/dist/cjs/mds-breadcrumb.cjs.entry.js +6 -5
- package/dist/cjs/mds-button-dropdown.cjs.entry.js +7 -6
- package/dist/cjs/mds-button-group.cjs.entry.js +5 -4
- package/dist/cjs/mds-button_3.cjs.entry.js +15 -12
- package/dist/cjs/mds-calendar_2.cjs.entry.js +190 -305
- package/dist/cjs/mds-card-content.cjs.entry.js +4 -3
- package/dist/cjs/mds-card-footer.cjs.entry.js +5 -4
- package/dist/cjs/mds-card-header.cjs.entry.js +4 -3
- package/dist/cjs/mds-card-media.cjs.entry.js +4 -3
- package/dist/cjs/mds-card.cjs.entry.js +6 -5
- package/dist/cjs/mds-details.cjs.entry.js +5 -4
- package/dist/cjs/mds-dropdown.cjs.entry.js +46 -17
- package/dist/cjs/mds-emoji.cjs.entry.js +5 -4
- package/dist/cjs/mds-entity.cjs.entry.js +5 -4
- package/dist/cjs/mds-file-preview.cjs.entry.js +7 -6
- package/dist/cjs/mds-file.cjs.entry.js +6 -5
- package/dist/cjs/mds-filter-item.cjs.entry.js +6 -5
- package/dist/cjs/mds-filter.cjs.entry.js +6 -5
- package/dist/cjs/mds-header-bar.cjs.entry.js +6 -5
- package/dist/cjs/mds-header.cjs.entry.js +5 -4
- package/dist/cjs/mds-horizontal-scroll.cjs.entry.js +6 -5
- package/dist/cjs/mds-hr.cjs.entry.js +5 -4
- package/dist/cjs/mds-img.cjs.entry.js +5 -4
- package/dist/cjs/mds-input-date-range-preselection.cjs.entry.js +4 -3
- package/dist/cjs/mds-input-date-range.cjs.entry.js +126 -31
- package/dist/cjs/mds-input-date.cjs.entry.js +26 -12
- package/dist/cjs/mds-input-field.cjs.entry.js +4 -3
- package/dist/cjs/mds-input-otp.cjs.entry.js +6 -5
- package/dist/cjs/mds-input-range-value.cjs.entry.js +18 -0
- package/dist/cjs/mds-input-range.cjs.entry.js +410 -29
- package/dist/cjs/mds-input-select.cjs.entry.js +9 -8
- package/dist/cjs/mds-input-switch_2.cjs.entry.js +9 -7
- package/dist/cjs/mds-input-tip_2.cjs.entry.js +17 -12
- package/dist/cjs/mds-input-upload.cjs.entry.js +10 -9
- package/dist/cjs/mds-input.cjs.entry.js +292 -35
- package/dist/cjs/mds-keyboard-key.cjs.entry.js +6 -5
- package/dist/cjs/mds-keyboard.cjs.entry.js +6 -5
- package/dist/cjs/mds-kpi-item.cjs.entry.js +5 -4
- package/dist/cjs/mds-kpi.cjs.entry.js +4 -3
- package/dist/cjs/mds-label.cjs.entry.js +6 -5
- package/dist/cjs/mds-link.cjs.entry.js +9 -8
- package/dist/cjs/mds-list-item.cjs.entry.js +4 -3
- package/dist/cjs/mds-list.cjs.entry.js +4 -3
- package/dist/cjs/mds-mention.cjs.entry.js +6 -5
- package/dist/cjs/mds-modal.cjs.entry.js +7 -6
- package/dist/cjs/mds-note.cjs.entry.js +6 -5
- package/dist/cjs/mds-notification.cjs.entry.js +6 -5
- package/dist/cjs/mds-paginator-item.cjs.entry.js +5 -4
- package/dist/cjs/mds-paginator.cjs.entry.js +6 -5
- package/dist/cjs/mds-policy-ai.cjs.entry.js +6 -5
- package/dist/cjs/mds-pref-animation.cjs.entry.js +6 -5
- package/dist/cjs/mds-pref-consumption.cjs.entry.js +6 -5
- package/dist/cjs/mds-pref-contrast.cjs.entry.js +6 -5
- package/dist/cjs/mds-pref-language-item.cjs.entry.js +6 -5
- package/dist/cjs/mds-pref-language.cjs.entry.js +6 -5
- package/dist/cjs/mds-pref-mode.cjs.entry.js +6 -5
- package/dist/cjs/mds-pref-theme-item.cjs.entry.js +4 -3
- package/dist/cjs/mds-pref-theme.cjs.entry.js +6 -5
- package/dist/cjs/mds-pref.cjs.entry.js +12 -6
- package/dist/cjs/mds-price-table-features-cell.cjs.entry.js +5 -4
- package/dist/cjs/mds-price-table-features-row.cjs.entry.js +5 -4
- package/dist/cjs/mds-price-table-features.cjs.entry.js +5 -4
- package/dist/cjs/mds-price-table-header.cjs.entry.js +4 -3
- package/dist/cjs/mds-price-table-list-item.cjs.entry.js +4 -3
- package/dist/cjs/mds-price-table-list.cjs.entry.js +5 -4
- package/dist/cjs/mds-price-table.cjs.entry.js +4 -3
- package/dist/cjs/mds-progress_2.cjs.entry.js +13 -8
- package/dist/cjs/mds-push-notification-item.cjs.entry.js +7 -6
- package/dist/cjs/mds-push-notification.cjs.entry.js +6 -5
- package/dist/cjs/mds-quote.cjs.entry.js +5 -4
- package/dist/cjs/mds-radial-menu-item.cjs.entry.js +4 -3
- package/dist/cjs/mds-radial-menu.cjs.entry.js +8 -7
- package/dist/cjs/mds-separator.cjs.entry.js +5 -4
- package/dist/cjs/mds-status-bar.cjs.entry.js +5 -4
- package/dist/cjs/mds-stepper-bar-item.cjs.entry.js +7 -6
- package/dist/cjs/mds-stepper-bar.cjs.entry.js +6 -6
- package/dist/cjs/mds-tab-bar-item.cjs.entry.js +5 -4
- package/dist/cjs/mds-tab-bar.cjs.entry.js +5 -4
- package/dist/cjs/mds-tab_2.cjs.entry.js +41 -17
- package/dist/cjs/mds-table-body.cjs.entry.js +5 -4
- package/dist/cjs/mds-table-footer.cjs.entry.js +5 -4
- package/dist/cjs/mds-table-header-cell.cjs.entry.js +5 -4
- package/dist/cjs/mds-table-header.cjs.entry.js +14 -14
- package/dist/cjs/mds-table-row.cjs.entry.js +7 -6
- package/dist/cjs/mds-table.cjs.entry.js +42 -14
- package/dist/cjs/mds-text.cjs.entry.js +5 -4
- package/dist/cjs/mds-toast-region.cjs.entry.js +4 -3
- package/dist/cjs/mds-toast.cjs.entry.js +6 -5
- package/dist/cjs/mds-tooltip.cjs.entry.js +33 -14
- package/dist/cjs/mds-tree-item.cjs.entry.js +6 -5
- package/dist/cjs/mds-tree.cjs.entry.js +4 -3
- package/dist/cjs/mds-url-view.cjs.entry.js +6 -18
- package/dist/cjs/mds-usage.cjs.entry.js +6 -5
- package/dist/cjs/mds-video-wall.cjs.entry.js +5 -4
- package/dist/cjs/mds-zero.cjs.entry.js +15 -5
- package/dist/cjs/{navigation-5yeOyO6F.js → navigation-Dxea9mKE.js} +7 -0
- package/dist/cjs/{preference-DhNxLZ4R.js → preference-DTUJPGHS.js} +1 -1
- package/dist/collection/collection-manifest.json +2 -1
- package/dist/collection/common/floating-controller.js +50 -3
- package/dist/collection/common/navigation.js +7 -0
- package/dist/collection/common/validity/index.js +3 -0
- package/dist/collection/components/mds-accordion/AGENTS.md +2 -2
- package/dist/collection/components/mds-accordion/documentation.json +5 -4
- package/dist/collection/components/mds-accordion/examples.md +3 -3
- package/dist/collection/components/mds-accordion/mds-accordion.js +1 -1
- package/dist/collection/components/mds-accordion-item/AGENTS.md +5 -3
- package/dist/collection/components/mds-accordion-item/documentation.json +60 -5
- package/dist/collection/components/mds-accordion-item/examples.md +5 -3
- package/dist/collection/components/mds-accordion-item/mds-accordion-item.css +9 -0
- package/dist/collection/components/mds-accordion-item/mds-accordion-item.js +32 -4
- package/dist/collection/components/mds-accordion-timer/AGENTS.md +1 -1
- package/dist/collection/components/mds-accordion-timer/documentation.json +3 -2
- package/dist/collection/components/mds-accordion-timer/mds-accordion-timer.js +1 -1
- package/dist/collection/components/mds-accordion-timer-item/AGENTS.md +6 -4
- package/dist/collection/components/mds-accordion-timer-item/documentation.json +64 -9
- package/dist/collection/components/mds-accordion-timer-item/examples.md +5 -3
- package/dist/collection/components/mds-accordion-timer-item/mds-accordion-timer-item.css +9 -0
- package/dist/collection/components/mds-accordion-timer-item/mds-accordion-timer-item.js +32 -4
- package/dist/collection/components/mds-author/AGENTS.md +1 -1
- package/dist/collection/components/mds-author/documentation.json +3 -2
- package/dist/collection/components/mds-author/mds-author.js +1 -1
- package/dist/collection/components/mds-avatar/AGENTS.md +1 -1
- package/dist/collection/components/mds-avatar/documentation.json +3 -2
- package/dist/collection/components/mds-avatar/mds-avatar.js +1 -1
- package/dist/collection/components/mds-avatar-stack/AGENTS.md +1 -1
- package/dist/collection/components/mds-avatar-stack/documentation.json +3 -2
- package/dist/collection/components/mds-avatar-stack/mds-avatar-stack.js +1 -1
- package/dist/collection/components/mds-avatar-stack-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-avatar-stack-item/documentation.json +3 -2
- package/dist/collection/components/mds-avatar-stack-item/mds-avatar-stack-item.js +1 -1
- package/dist/collection/components/mds-badge/AGENTS.md +1 -1
- package/dist/collection/components/mds-badge/documentation.json +3 -2
- package/dist/collection/components/mds-badge/mds-badge.js +1 -1
- package/dist/collection/components/mds-banner/AGENTS.md +4 -1
- package/dist/collection/components/mds-banner/documentation.json +44 -5
- package/dist/collection/components/mds-banner/examples.md +15 -9
- package/dist/collection/components/mds-banner/mds-banner.js +63 -19
- package/dist/collection/components/mds-banner/meta/dictionary.js +7 -0
- package/dist/collection/components/mds-banner/meta/types.js +1 -0
- package/dist/collection/components/mds-banner/mistakes.md +20 -0
- package/dist/collection/components/mds-benchmark-bar/AGENTS.md +1 -1
- package/dist/collection/components/mds-benchmark-bar/documentation.json +3 -2
- package/dist/collection/components/mds-benchmark-bar/mds-benchmark-bar.js +1 -1
- package/dist/collection/components/mds-bibliography/AGENTS.md +1 -1
- package/dist/collection/components/mds-bibliography/documentation.json +3 -2
- package/dist/collection/components/mds-bibliography/mds-bibliography.js +1 -1
- package/dist/collection/components/mds-book/AGENTS.md +1 -1
- package/dist/collection/components/mds-book/documentation.json +3 -2
- package/dist/collection/components/mds-book/mds-book.js +3 -3
- package/dist/collection/components/mds-breadcrumb/AGENTS.md +1 -1
- package/dist/collection/components/mds-breadcrumb/documentation.json +3 -2
- package/dist/collection/components/mds-breadcrumb/mds-breadcrumb.js +1 -1
- package/dist/collection/components/mds-breadcrumb-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-breadcrumb-item/documentation.json +3 -2
- package/dist/collection/components/mds-breadcrumb-item/mds-breadcrumb-item.js +1 -1
- package/dist/collection/components/mds-button/AGENTS.md +1 -1
- package/dist/collection/components/mds-button/documentation.json +3 -2
- package/dist/collection/components/mds-button/mds-button.js +4 -4
- package/dist/collection/components/mds-button-dropdown/AGENTS.md +3 -1
- package/dist/collection/components/mds-button-dropdown/documentation.json +5 -4
- package/dist/collection/components/mds-button-dropdown/examples.md +16 -0
- package/dist/collection/components/mds-button-dropdown/mds-button-dropdown.css +12 -0
- package/dist/collection/components/mds-button-dropdown/mds-button-dropdown.js +1 -1
- package/dist/collection/components/mds-button-group/AGENTS.md +3 -2
- package/dist/collection/components/mds-button-group/documentation.json +5 -4
- package/dist/collection/components/mds-button-group/examples.md +16 -0
- package/dist/collection/components/mds-button-group/mds-button-group.css +13 -0
- package/dist/collection/components/mds-button-group/mds-button-group.js +1 -1
- package/dist/collection/components/mds-calendar/AGENTS.md +8 -4
- package/dist/collection/components/mds-calendar/documentation.json +44 -5
- package/dist/collection/components/mds-calendar/examples.md +17 -1
- package/dist/collection/components/mds-calendar/mds-calendar.css +4 -0
- package/dist/collection/components/mds-calendar/mds-calendar.js +206 -300
- package/dist/collection/components/mds-calendar/meta/types.js +1 -0
- package/dist/collection/components/mds-calendar/mistakes.md +1 -1
- package/dist/collection/components/mds-calendar-cell/AGENTS.md +4 -4
- package/dist/collection/components/mds-calendar-cell/documentation.json +37 -24
- package/dist/collection/components/mds-calendar-cell/examples.md +3 -3
- package/dist/collection/components/mds-calendar-cell/mds-calendar-cell.css +121 -84
- package/dist/collection/components/mds-calendar-cell/mds-calendar-cell.js +1 -1
- package/dist/collection/components/mds-card/AGENTS.md +4 -2
- package/dist/collection/components/mds-card/documentation.json +12 -5
- package/dist/collection/components/mds-card/examples.md +6 -1
- package/dist/collection/components/mds-card/mds-card.css +8 -0
- package/dist/collection/components/mds-card/mds-card.js +1 -1
- package/dist/collection/components/mds-card/mistakes.md +1 -1
- package/dist/collection/components/mds-card-content/AGENTS.md +1 -1
- package/dist/collection/components/mds-card-content/documentation.json +3 -2
- package/dist/collection/components/mds-card-content/mds-card-content.js +1 -1
- package/dist/collection/components/mds-card-footer/AGENTS.md +2 -2
- package/dist/collection/components/mds-card-footer/documentation.json +5 -4
- package/dist/collection/components/mds-card-footer/examples.md +1 -1
- package/dist/collection/components/mds-card-footer/mds-card-footer.css +9 -0
- 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 +3 -2
- 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 +3 -2
- package/dist/collection/components/mds-card-media/mds-card-media.js +1 -1
- package/dist/collection/components/mds-chip/AGENTS.md +5 -2
- package/dist/collection/components/mds-chip/documentation.json +37 -5
- package/dist/collection/components/mds-chip/examples.md +10 -0
- package/dist/collection/components/mds-chip/mds-chip.css +18 -0
- package/dist/collection/components/mds-chip/mds-chip.js +25 -1
- package/dist/collection/components/mds-chip/mistakes.md +25 -1
- package/dist/collection/components/mds-details/AGENTS.md +1 -1
- package/dist/collection/components/mds-details/documentation.json +3 -2
- 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 +4 -3
- package/dist/collection/components/mds-dropdown/mds-dropdown.js +40 -12
- package/dist/collection/components/mds-dropdown/mistakes.md +1 -1
- package/dist/collection/components/mds-emoji/AGENTS.md +1 -1
- package/dist/collection/components/mds-emoji/documentation.json +3 -2
- 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 +3 -2
- package/dist/collection/components/mds-entity/mds-entity.js +1 -1
- package/dist/collection/components/mds-file/AGENTS.md +1 -1
- package/dist/collection/components/mds-file/documentation.json +3 -2
- package/dist/collection/components/mds-file/mds-file.js +1 -1
- package/dist/collection/components/mds-file-preview/AGENTS.md +1 -1
- package/dist/collection/components/mds-file-preview/documentation.json +3 -2
- package/dist/collection/components/mds-file-preview/mds-file-preview.js +2 -2
- package/dist/collection/components/mds-filter/AGENTS.md +1 -1
- package/dist/collection/components/mds-filter/documentation.json +3 -2
- package/dist/collection/components/mds-filter/mds-filter.js +1 -1
- package/dist/collection/components/mds-filter-item/AGENTS.md +2 -2
- package/dist/collection/components/mds-filter-item/documentation.json +5 -4
- package/dist/collection/components/mds-filter-item/mds-filter-item.js +1 -1
- package/dist/collection/components/mds-filter-item/mistakes.md +16 -0
- package/dist/collection/components/mds-header/AGENTS.md +1 -1
- package/dist/collection/components/mds-header/documentation.json +3 -2
- package/dist/collection/components/mds-header/mds-header.js +1 -1
- package/dist/collection/components/mds-header-bar/AGENTS.md +1 -1
- package/dist/collection/components/mds-header-bar/documentation.json +3 -2
- package/dist/collection/components/mds-header-bar/mds-header-bar.js +1 -1
- package/dist/collection/components/mds-help/AGENTS.md +1 -1
- package/dist/collection/components/mds-help/documentation.json +3 -2
- package/dist/collection/components/mds-help/mds-help.js +1 -1
- package/dist/collection/components/mds-horizontal-scroll/AGENTS.md +1 -1
- package/dist/collection/components/mds-horizontal-scroll/documentation.json +3 -2
- package/dist/collection/components/mds-horizontal-scroll/mds-horizontal-scroll.js +1 -1
- package/dist/collection/components/mds-hr/AGENTS.md +1 -1
- package/dist/collection/components/mds-hr/documentation.json +3 -2
- package/dist/collection/components/mds-hr/mds-hr.js +1 -1
- package/dist/collection/components/mds-icon/AGENTS.md +2 -2
- package/dist/collection/components/mds-icon/documentation.json +5 -4
- package/dist/collection/components/mds-icon/examples.md +3 -3
- package/dist/collection/components/mds-icon/mds-icon.js +1 -1
- package/dist/collection/components/mds-icon/services/icons-set.service.js +43 -1
- package/dist/collection/components/mds-img/AGENTS.md +1 -1
- package/dist/collection/components/mds-img/documentation.json +3 -2
- package/dist/collection/components/mds-input/AGENTS.md +22 -18
- package/dist/collection/components/mds-input/documentation.json +32 -19
- package/dist/collection/components/mds-input/examples.md +20 -3
- package/dist/collection/components/mds-input/mds-input.css +115 -8
- package/dist/collection/components/mds-input/mds-input.js +236 -37
- package/dist/collection/components/mds-input/meta/color.js +19 -0
- package/dist/collection/components/mds-input/meta/input-type/InputValidationManager.js +5 -1
- package/dist/collection/components/mds-input/meta/validators.js +10 -0
- package/dist/collection/components/mds-input/meta/validity.js +5 -2
- package/dist/collection/components/mds-input/mistakes.md +15 -1
- package/dist/collection/components/mds-input-date/AGENTS.md +7 -7
- package/dist/collection/components/mds-input-date/documentation.json +7 -24
- package/dist/collection/components/mds-input-date/examples.md +1 -1
- package/dist/collection/components/mds-input-date/mds-input-date.css +17 -15
- package/dist/collection/components/mds-input-date/mds-input-date.js +21 -8
- package/dist/collection/components/mds-input-date-range/AGENTS.md +10 -7
- package/dist/collection/components/mds-input-date-range/documentation.json +16 -8
- package/dist/collection/components/mds-input-date-range/examples.md +12 -1
- package/dist/collection/components/mds-input-date-range/mds-input-date-range.css +15 -0
- package/dist/collection/components/mds-input-date-range/mds-input-date-range.js +90 -27
- package/dist/collection/components/mds-input-date-range-preselection/AGENTS.md +1 -1
- package/dist/collection/components/mds-input-date-range-preselection/documentation.json +3 -2
- 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 +3 -2
- 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 +3 -2
- package/dist/collection/components/mds-input-otp/mds-input-otp.js +1 -1
- package/dist/collection/components/mds-input-range/AGENTS.md +27 -8
- package/dist/collection/components/mds-input-range/documentation.json +31 -9
- package/dist/collection/components/mds-input-range/examples.md +41 -0
- package/dist/collection/components/mds-input-range/mds-input-range.css +68 -5
- package/dist/collection/components/mds-input-range/mds-input-range.js +440 -29
- package/dist/collection/components/mds-input-range/meta/event-detail.js +1 -0
- package/dist/collection/components/mds-input-range/mistakes.md +37 -0
- package/dist/collection/components/mds-input-range-value/AGENTS.md +43 -0
- package/dist/collection/components/mds-input-range-value/documentation.json +77 -0
- package/dist/collection/components/mds-input-range-value/examples.md +66 -0
- package/dist/collection/components/mds-input-range-value/mds-input-range-value.css +6 -0
- package/dist/collection/components/mds-input-range-value/mds-input-range-value.js +50 -0
- package/dist/collection/components/mds-input-range-value/mistakes.md +56 -0
- package/dist/collection/components/mds-input-select/AGENTS.md +2 -2
- package/dist/collection/components/mds-input-select/documentation.json +4 -3
- package/dist/collection/components/mds-input-select/mds-input-select.css +9 -19
- package/dist/collection/components/mds-input-select/mds-input-select.js +2 -2
- package/dist/collection/components/mds-input-switch/AGENTS.md +1 -1
- package/dist/collection/components/mds-input-switch/documentation.json +3 -2
- package/dist/collection/components/mds-input-switch/mds-input-switch.js +1 -1
- package/dist/collection/components/mds-input-tip/AGENTS.md +7 -6
- package/dist/collection/components/mds-input-tip/documentation.json +17 -10
- package/dist/collection/components/mds-input-tip/examples.md +2 -2
- package/dist/collection/components/mds-input-tip/mds-input-tip.css +15 -17
- package/dist/collection/components/mds-input-tip/mds-input-tip.js +9 -6
- package/dist/collection/components/mds-input-tip-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-input-tip-item/documentation.json +3 -2
- package/dist/collection/components/mds-input-tip-item/mds-input-tip-item.js +2 -2
- package/dist/collection/components/mds-input-tip-item/meta/dictionary.js +1 -1
- package/dist/collection/components/mds-input-upload/AGENTS.md +1 -1
- package/dist/collection/components/mds-input-upload/documentation.json +3 -2
- 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 +3 -2
- 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 +3 -2
- 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 +3 -2
- 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 +3 -2
- 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 +3 -2
- package/dist/collection/components/mds-label/mds-label.js +1 -1
- package/dist/collection/components/mds-link/AGENTS.md +1 -1
- package/dist/collection/components/mds-link/documentation.json +3 -2
- package/dist/collection/components/mds-link/mds-link.js +3 -3
- package/dist/collection/components/mds-list/AGENTS.md +1 -1
- package/dist/collection/components/mds-list/documentation.json +3 -2
- package/dist/collection/components/mds-list/mds-list.js +1 -1
- package/dist/collection/components/mds-list-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-list-item/documentation.json +3 -2
- package/dist/collection/components/mds-list-item/mds-list-item.js +1 -1
- package/dist/collection/components/mds-mention/AGENTS.md +1 -1
- package/dist/collection/components/mds-mention/documentation.json +3 -2
- package/dist/collection/components/mds-mention/mds-mention.js +1 -1
- package/dist/collection/components/mds-modal/AGENTS.md +2 -1
- package/dist/collection/components/mds-modal/documentation.json +5 -4
- package/dist/collection/components/mds-modal/examples.md +2 -0
- package/dist/collection/components/mds-modal/mds-modal.js +2 -2
- package/dist/collection/components/mds-note/AGENTS.md +1 -1
- package/dist/collection/components/mds-note/documentation.json +3 -2
- 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 +3 -2
- 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 +3 -2
- 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 +3 -2
- 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 +3 -2
- package/dist/collection/components/mds-policy-ai/mds-policy-ai.js +1 -1
- package/dist/collection/components/mds-pref/AGENTS.md +4 -1
- package/dist/collection/components/mds-pref/documentation.json +31 -4
- package/dist/collection/components/mds-pref/examples.md +14 -0
- package/dist/collection/components/mds-pref/mds-pref.js +26 -2
- package/dist/collection/components/mds-pref-animation/AGENTS.md +1 -1
- package/dist/collection/components/mds-pref-animation/documentation.json +3 -2
- 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 +3 -2
- 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 +3 -2
- package/dist/collection/components/mds-pref-contrast/mds-pref-contrast.js +1 -1
- package/dist/collection/components/mds-pref-language/AGENTS.md +2 -2
- package/dist/collection/components/mds-pref-language/documentation.json +4 -3
- 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 +3 -2
- package/dist/collection/components/mds-pref-language-item/mds-pref-language-item.js +1 -1
- package/dist/collection/components/mds-pref-mode/AGENTS.md +1 -1
- package/dist/collection/components/mds-pref-mode/documentation.json +3 -2
- package/dist/collection/components/mds-pref-mode/mds-pref-mode.js +1 -1
- package/dist/collection/components/mds-pref-theme/AGENTS.md +1 -1
- package/dist/collection/components/mds-pref-theme/documentation.json +3 -2
- package/dist/collection/components/mds-pref-theme/mds-pref-theme.js +1 -1
- package/dist/collection/components/mds-pref-theme-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-pref-theme-item/documentation.json +3 -2
- package/dist/collection/components/mds-pref-theme-item/mds-pref-theme-item.js +1 -1
- package/dist/collection/components/mds-price-table/AGENTS.md +1 -1
- package/dist/collection/components/mds-price-table/documentation.json +3 -2
- 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 +3 -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 +3 -2
- 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 +3 -2
- 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 +3 -2
- 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 +3 -2
- 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 +3 -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 +3 -2
- 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 +3 -2
- 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 +3 -2
- 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 +3 -2
- package/dist/collection/components/mds-quote/mds-quote.js +1 -1
- package/dist/collection/components/mds-radial-menu/AGENTS.md +1 -1
- package/dist/collection/components/mds-radial-menu/documentation.json +3 -2
- package/dist/collection/components/mds-radial-menu/mds-radial-menu.js +1 -1
- package/dist/collection/components/mds-radial-menu-item/AGENTS.md +1 -1
- package/dist/collection/components/mds-radial-menu-item/documentation.json +3 -2
- 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 +3 -2
- package/dist/collection/components/mds-radial-progress/mds-radial-progress.css +4 -2
- package/dist/collection/components/mds-radial-progress/mds-radial-progress.js +5 -2
- package/dist/collection/components/mds-separator/AGENTS.md +1 -1
- package/dist/collection/components/mds-separator/documentation.json +3 -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 +3 -2
- 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 +3 -2
- 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 +3 -2
- package/dist/collection/components/mds-stepper-bar/mds-stepper-bar.js +3 -4
- package/dist/collection/components/mds-stepper-bar-item/AGENTS.md +2 -2
- package/dist/collection/components/mds-stepper-bar-item/documentation.json +5 -4
- package/dist/collection/components/mds-stepper-bar-item/examples.md +1 -1
- package/dist/collection/components/mds-stepper-bar-item/mds-stepper-bar-item.css +7 -2
- package/dist/collection/components/mds-stepper-bar-item/mds-stepper-bar-item.js +1 -1
- package/dist/collection/components/mds-tab/AGENTS.md +3 -3
- package/dist/collection/components/mds-tab/documentation.json +8 -3
- package/dist/collection/components/mds-tab/mds-tab.js +34 -12
- package/dist/collection/components/mds-tab-bar/AGENTS.md +1 -1
- package/dist/collection/components/mds-tab-bar/documentation.json +3 -2
- 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 +3 -2
- package/dist/collection/components/mds-tab-bar-item/mds-tab-bar-item.js +1 -1
- package/dist/collection/components/mds-tab-item/AGENTS.md +2 -2
- package/dist/collection/components/mds-tab-item/documentation.json +7 -2
- package/dist/collection/components/mds-tab-item/mds-tab-item.js +1 -1
- package/dist/collection/components/mds-table/AGENTS.md +4 -4
- package/dist/collection/components/mds-table/documentation.json +10 -9
- package/dist/collection/components/mds-table/examples.md +21 -0
- package/dist/collection/components/mds-table/mds-table.js +42 -15
- package/dist/collection/components/mds-table-body/AGENTS.md +1 -1
- package/dist/collection/components/mds-table-body/documentation.json +3 -2
- 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 +3 -2
- 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 +3 -2
- package/dist/collection/components/mds-table-footer/mds-table-footer.js +1 -1
- package/dist/collection/components/mds-table-header/AGENTS.md +3 -3
- package/dist/collection/components/mds-table-header/documentation.json +5 -8
- package/dist/collection/components/mds-table-header/mds-table-header.js +9 -14
- package/dist/collection/components/mds-table-header/mistakes.md +1 -1
- package/dist/collection/components/mds-table-header-cell/AGENTS.md +1 -1
- package/dist/collection/components/mds-table-header-cell/documentation.json +3 -2
- package/dist/collection/components/mds-table-header-cell/mds-table-header-cell.js +1 -1
- package/dist/collection/components/mds-table-row/AGENTS.md +2 -2
- package/dist/collection/components/mds-table-row/documentation.json +4 -3
- package/dist/collection/components/mds-table-row/mds-table-row.js +2 -2
- package/dist/collection/components/mds-text/AGENTS.md +1 -1
- package/dist/collection/components/mds-text/documentation.json +3 -2
- package/dist/collection/components/mds-text/mds-text.js +1 -1
- package/dist/collection/components/mds-toast/AGENTS.md +1 -1
- package/dist/collection/components/mds-toast/documentation.json +3 -2
- package/dist/collection/components/mds-toast/mds-toast.js +1 -1
- package/dist/collection/components/mds-toast-region/AGENTS.md +1 -1
- package/dist/collection/components/mds-toast-region/documentation.json +3 -2
- package/dist/collection/components/mds-toast-region/mds-toast-region.js +1 -1
- package/dist/collection/components/mds-tooltip/AGENTS.md +1 -1
- package/dist/collection/components/mds-tooltip/documentation.json +3 -2
- package/dist/collection/components/mds-tooltip/mds-tooltip.js +27 -9
- package/dist/collection/components/mds-tree/AGENTS.md +1 -1
- package/dist/collection/components/mds-tree/documentation.json +3 -2
- 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 +3 -2
- 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 +3 -2
- package/dist/collection/components/mds-url-view/mds-url-view.js +1 -14
- package/dist/collection/components/mds-usage/AGENTS.md +1 -1
- package/dist/collection/components/mds-usage/documentation.json +3 -2
- package/dist/collection/components/mds-usage/mds-usage.js +1 -1
- package/dist/collection/components/mds-video-wall/AGENTS.md +1 -1
- package/dist/collection/components/mds-video-wall/documentation.json +3 -2
- package/dist/collection/components/mds-video-wall/mds-video-wall.js +1 -1
- package/dist/collection/components/mds-zero/AGENTS.md +7 -6
- package/dist/collection/components/mds-zero/documentation.json +6 -5
- package/dist/collection/components/mds-zero/examples.md +37 -19
- package/dist/collection/components/mds-zero/mds-zero.css +22 -24
- package/dist/collection/components/mds-zero/mds-zero.js +17 -1
- package/dist/collection/components/mds-zero/mistakes.md +46 -8
- package/dist/collection/fixtures/dark-mode.js +16 -0
- package/dist/collection/index.js +2 -20
- package/dist/collection/type/file-types.js +1 -1
- package/dist/collection/type/input.js +1 -0
- package/dist/components/index.d.ts +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-author.js +1 -1
- package/dist/components/mds-avatar-stack-item.js +1 -1
- package/dist/components/mds-avatar-stack.js +1 -1
- package/dist/components/mds-avatar.js +1 -1
- package/dist/components/mds-badge.js +1 -1
- package/dist/components/mds-banner.js +1 -1
- package/dist/components/mds-benchmark-bar.js +1 -1
- package/dist/components/mds-bibliography.js +1 -1
- package/dist/components/mds-book.js +1 -1
- package/dist/components/mds-breadcrumb-item.js +1 -1
- package/dist/components/mds-breadcrumb.js +1 -1
- package/dist/components/mds-button-dropdown.js +1 -1
- package/dist/components/mds-button-group.js +1 -1
- package/dist/components/mds-button.js +1 -1
- package/dist/components/mds-calendar-cell.js +1 -1
- package/dist/components/mds-calendar.js +1 -1
- package/dist/components/mds-card-content.js +1 -1
- package/dist/components/mds-card-footer.js +1 -1
- package/dist/components/mds-card-header.js +1 -1
- package/dist/components/mds-card-media.js +1 -1
- package/dist/components/mds-card.js +1 -1
- package/dist/components/mds-chip.js +1 -1
- package/dist/components/mds-details.js +1 -1
- package/dist/components/mds-dropdown.js +1 -1
- package/dist/components/mds-emoji.js +3 -3
- package/dist/components/mds-entity.js +1 -1
- package/dist/components/mds-file-preview.js +1 -1
- package/dist/components/mds-file.js +1 -1
- 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-value.d.ts +11 -0
- package/dist/components/mds-input-range-value.js +1 -0
- 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-link.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-region.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-Bbrei_yQ.js → p-AWCYh8Xe.js} +1 -1
- package/dist/components/{p-ClvoVgmw.js → p-B-GgEAg7.js} +1 -1
- package/dist/components/p-B3npFzUR.js +1 -0
- package/dist/components/p-BD9VWE7b.js +1 -0
- package/dist/components/{p-BBZyH3mn.js → p-BFZN4zJ9.js} +1 -1
- package/dist/components/p-BG1fjwnd.js +1 -0
- package/dist/components/{p-BI1ShBQG.js → p-BNl6YWNN.js} +1 -1
- package/dist/components/{p-BE05D6Pe.js → p-Bg11_7lt.js} +1 -1
- package/dist/components/{p-3rr6yzu-.js → p-BiJ4xa4V.js} +1 -1
- package/dist/components/{p-CvbuCEYD.js → p-BmlDGlcB.js} +2 -2
- package/dist/components/p-C0m6B_kt.js +1 -0
- package/dist/components/{p-j5Hnbfv9.js → p-C589Hkfn.js} +1 -1
- package/dist/components/{p-BaFfIZGB.js → p-C7p9e0P3.js} +1 -1
- package/dist/components/{p-Vgo7t88R.js → p-C878c9Nu.js} +1 -1
- package/dist/components/{p-CWOW2Vna.js → p-CDcB9Zdz.js} +1 -1
- package/dist/components/{p-CZwKeFQT.js → p-CS8s4gRV.js} +1 -1
- package/dist/components/p-CSw6DbKp.js +1 -0
- package/dist/components/p-CUT9aFzz.js +1 -0
- package/dist/components/p-CfCw1XZP.js +1 -0
- package/dist/components/{p-BpND63Kl.js → p-Cjy1i94z.js} +1 -1
- package/dist/components/{p-Do7IoDLD.js → p-Cs80Zm2b.js} +2 -2
- package/dist/components/{p-NNPsVjnj.js → p-Cs8RIbsQ.js} +1 -1
- package/dist/components/p-CtEHhdv4.js +1 -0
- package/dist/components/{p-F0qhFsF0.js → p-Cty6fegI.js} +1 -1
- package/dist/components/{p-C6LU1s8K.js → p-D7C-gjL6.js} +1 -1
- package/dist/components/{p-DrtIqOQn.js → p-DKYN6Ikh.js} +1 -1
- package/dist/components/p-DvccsLwr.js +1 -0
- package/dist/components/{p-CrOv4KdL.js → p-DxNrlomi.js} +1 -1
- package/dist/components/p-G8GFHw3L.js +1 -0
- package/dist/components/p-MjWyZlga.js +1 -0
- package/dist/components/p-VoGfNJRY.js +1 -0
- package/dist/components/{p-BuhoBOYR.js → p-WFNxKo1V.js} +1 -1
- package/dist/components/{p-DN1yF-xO.js → p-aZlZ1XB9.js} +1 -1
- package/dist/components/p-g2_CekDc.js +3 -0
- package/dist/components/p-kS9VRIWa.js +1 -0
- package/dist/components/{p-BBrPpCNK.js → p-oHBGZ2Av.js} +1 -1
- package/dist/documentation.json +530 -157
- package/dist/esm/{floating-controller-xixU_s1w.js → floating-controller-DlFrvBTG.js} +51 -4
- package/dist/esm/{floating-ui.dom-BaFfIZGB.js → floating-ui.dom-C7p9e0P3.js} +1 -1
- package/dist/esm/{index-CvLLN-QH.js → index-CPibDZjX.js} +87 -44
- package/dist/esm/{index-DEL0bLpb.js → index-DWniH_Ge.js} +12 -1
- package/dist/esm/index.js +45 -3
- package/dist/esm/loader.js +3 -3
- package/dist/esm/{locale-DhP1Ge2o.js → locale-B7Hw4niB.js} +1 -1
- package/dist/esm/magma-components.js +4 -4
- package/dist/esm/mds-accordion-item.entry.js +10 -7
- package/dist/esm/mds-accordion-timer-item.entry.js +10 -7
- package/dist/esm/mds-accordion-timer.entry.js +4 -3
- package/dist/esm/mds-accordion.entry.js +5 -4
- package/dist/esm/mds-author.entry.js +4 -3
- package/dist/esm/mds-avatar-stack-item.entry.js +4 -3
- package/dist/esm/mds-avatar-stack.entry.js +4 -3
- package/dist/esm/mds-avatar.entry.js +5 -4
- package/dist/esm/mds-badge.entry.js +5 -4
- package/dist/esm/mds-banner_3.entry.js +56 -27
- package/dist/esm/mds-benchmark-bar.entry.js +4 -3
- package/dist/esm/mds-bibliography.entry.js +4 -3
- package/dist/esm/mds-book.entry.js +8 -7
- package/dist/esm/mds-breadcrumb-item.entry.js +4 -3
- package/dist/esm/mds-breadcrumb.entry.js +6 -5
- package/dist/esm/mds-button-dropdown.entry.js +7 -6
- package/dist/esm/mds-button-group.entry.js +5 -4
- package/dist/esm/mds-button_3.entry.js +15 -12
- package/dist/esm/mds-calendar_2.entry.js +190 -305
- package/dist/esm/mds-card-content.entry.js +4 -3
- package/dist/esm/mds-card-footer.entry.js +5 -4
- package/dist/esm/mds-card-header.entry.js +4 -3
- package/dist/esm/mds-card-media.entry.js +4 -3
- package/dist/esm/mds-card.entry.js +6 -5
- package/dist/esm/mds-details.entry.js +5 -4
- package/dist/esm/mds-dropdown.entry.js +46 -17
- package/dist/esm/mds-emoji.entry.js +5 -4
- package/dist/esm/mds-entity.entry.js +5 -4
- package/dist/esm/mds-file-preview.entry.js +7 -6
- package/dist/esm/mds-file.entry.js +6 -5
- package/dist/esm/mds-filter-item.entry.js +6 -5
- package/dist/esm/mds-filter.entry.js +6 -5
- package/dist/esm/mds-header-bar.entry.js +6 -5
- package/dist/esm/mds-header.entry.js +5 -4
- package/dist/esm/mds-horizontal-scroll.entry.js +6 -5
- package/dist/esm/mds-hr.entry.js +5 -4
- package/dist/esm/mds-img.entry.js +5 -4
- package/dist/esm/mds-input-date-range-preselection.entry.js +4 -3
- package/dist/esm/mds-input-date-range.entry.js +126 -31
- package/dist/esm/mds-input-date.entry.js +26 -12
- package/dist/esm/mds-input-field.entry.js +4 -3
- package/dist/esm/mds-input-otp.entry.js +6 -5
- package/dist/esm/mds-input-range-value.entry.js +16 -0
- package/dist/esm/mds-input-range.entry.js +410 -29
- package/dist/esm/mds-input-select.entry.js +9 -8
- package/dist/esm/mds-input-switch_2.entry.js +9 -7
- package/dist/esm/mds-input-tip_2.entry.js +17 -12
- package/dist/esm/mds-input-upload.entry.js +10 -9
- package/dist/esm/mds-input.entry.js +292 -35
- package/dist/esm/mds-keyboard-key.entry.js +6 -5
- package/dist/esm/mds-keyboard.entry.js +6 -5
- package/dist/esm/mds-kpi-item.entry.js +5 -4
- package/dist/esm/mds-kpi.entry.js +4 -3
- package/dist/esm/mds-label.entry.js +6 -5
- package/dist/esm/mds-link.entry.js +9 -8
- package/dist/esm/mds-list-item.entry.js +4 -3
- package/dist/esm/mds-list.entry.js +4 -3
- package/dist/esm/mds-mention.entry.js +6 -5
- package/dist/esm/mds-modal.entry.js +7 -6
- package/dist/esm/mds-note.entry.js +6 -5
- package/dist/esm/mds-notification.entry.js +6 -5
- package/dist/esm/mds-paginator-item.entry.js +5 -4
- package/dist/esm/mds-paginator.entry.js +6 -5
- package/dist/esm/mds-policy-ai.entry.js +6 -5
- package/dist/esm/mds-pref-animation.entry.js +6 -5
- package/dist/esm/mds-pref-consumption.entry.js +6 -5
- package/dist/esm/mds-pref-contrast.entry.js +6 -5
- package/dist/esm/mds-pref-language-item.entry.js +6 -5
- package/dist/esm/mds-pref-language.entry.js +6 -5
- package/dist/esm/mds-pref-mode.entry.js +6 -5
- package/dist/esm/mds-pref-theme-item.entry.js +4 -3
- package/dist/esm/mds-pref-theme.entry.js +6 -5
- package/dist/esm/mds-pref.entry.js +12 -6
- package/dist/esm/mds-price-table-features-cell.entry.js +5 -4
- package/dist/esm/mds-price-table-features-row.entry.js +5 -4
- package/dist/esm/mds-price-table-features.entry.js +5 -4
- package/dist/esm/mds-price-table-header.entry.js +4 -3
- package/dist/esm/mds-price-table-list-item.entry.js +4 -3
- package/dist/esm/mds-price-table-list.entry.js +5 -4
- package/dist/esm/mds-price-table.entry.js +4 -3
- package/dist/esm/mds-progress_2.entry.js +13 -8
- package/dist/esm/mds-push-notification-item.entry.js +7 -6
- package/dist/esm/mds-push-notification.entry.js +6 -5
- package/dist/esm/mds-quote.entry.js +5 -4
- package/dist/esm/mds-radial-menu-item.entry.js +4 -3
- package/dist/esm/mds-radial-menu.entry.js +8 -7
- package/dist/esm/mds-separator.entry.js +5 -4
- package/dist/esm/mds-status-bar.entry.js +5 -4
- package/dist/esm/mds-stepper-bar-item.entry.js +7 -6
- package/dist/esm/mds-stepper-bar.entry.js +6 -6
- package/dist/esm/mds-tab-bar-item.entry.js +5 -4
- package/dist/esm/mds-tab-bar.entry.js +5 -4
- package/dist/esm/mds-tab_2.entry.js +41 -17
- package/dist/esm/mds-table-body.entry.js +5 -4
- package/dist/esm/mds-table-footer.entry.js +5 -4
- package/dist/esm/mds-table-header-cell.entry.js +5 -4
- package/dist/esm/mds-table-header.entry.js +14 -14
- package/dist/esm/mds-table-row.entry.js +7 -6
- package/dist/esm/mds-table.entry.js +42 -14
- package/dist/esm/mds-text.entry.js +5 -4
- package/dist/esm/mds-toast-region.entry.js +4 -3
- package/dist/esm/mds-toast.entry.js +6 -5
- package/dist/esm/mds-tooltip.entry.js +33 -14
- package/dist/esm/mds-tree-item.entry.js +6 -5
- package/dist/esm/mds-tree.entry.js +4 -3
- package/dist/esm/mds-url-view.entry.js +6 -18
- package/dist/esm/mds-usage.entry.js +6 -5
- package/dist/esm/mds-video-wall.entry.js +5 -4
- package/dist/esm/mds-zero.entry.js +15 -5
- package/dist/esm/{navigation-Bz1eiKqd.js → navigation-To9IeLHs.js} +7 -0
- package/dist/esm/{preference-C8foBO86.js → preference-CBMLGSf7.js} +1 -1
- package/dist/esm-es5/{floating-controller-xixU_s1w.js → floating-controller-DlFrvBTG.js} +32 -12
- package/dist/esm-es5/{floating-ui.dom-BaFfIZGB.js → floating-ui.dom-C7p9e0P3.js} +18 -18
- package/dist/esm-es5/{index-CvLLN-QH.js → index-CPibDZjX.js} +30 -27
- package/dist/esm-es5/index-DWniH_Ge.js +13 -0
- package/dist/esm-es5/index.js +47 -5
- package/dist/esm-es5/loader.js +1 -1
- package/dist/esm-es5/{locale-DhP1Ge2o.js → locale-B7Hw4niB.js} +1 -1
- package/dist/esm-es5/magma-components.js +3 -3
- package/dist/esm-es5/mds-accordion-item.entry.js +6 -4
- package/dist/esm-es5/mds-accordion-timer-item.entry.js +6 -4
- package/dist/esm-es5/mds-accordion-timer.entry.js +4 -4
- package/dist/esm-es5/mds-accordion.entry.js +4 -4
- package/dist/esm-es5/mds-author.entry.js +1 -1
- package/dist/esm-es5/mds-avatar-stack-item.entry.js +2 -2
- package/dist/esm-es5/mds-avatar-stack.entry.js +2 -2
- package/dist/esm-es5/mds-avatar.entry.js +7 -7
- package/dist/esm-es5/mds-badge.entry.js +2 -2
- package/dist/esm-es5/mds-banner_3.entry.js +25 -6
- package/dist/esm-es5/mds-benchmark-bar.entry.js +3 -3
- package/dist/esm-es5/mds-bibliography.entry.js +6 -6
- package/dist/esm-es5/mds-book.entry.js +22 -22
- package/dist/esm-es5/mds-breadcrumb-item.entry.js +2 -2
- package/dist/esm-es5/mds-breadcrumb.entry.js +4 -4
- package/dist/esm-es5/mds-button-dropdown.entry.js +5 -5
- package/dist/esm-es5/mds-button-group.entry.js +1 -1
- package/dist/esm-es5/mds-button_3.entry.js +20 -20
- package/dist/esm-es5/mds-calendar_2.entry.js +56 -14
- 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 +3 -3
- package/dist/esm-es5/mds-details.entry.js +3 -3
- package/dist/esm-es5/mds-dropdown.entry.js +31 -16
- package/dist/esm-es5/mds-emoji.entry.js +44 -44
- package/dist/esm-es5/mds-entity.entry.js +1 -1
- package/dist/esm-es5/mds-file-preview.entry.js +5 -5
- package/dist/esm-es5/mds-file.entry.js +7 -7
- package/dist/esm-es5/mds-filter-item.entry.js +4 -4
- package/dist/esm-es5/mds-filter.entry.js +7 -7
- package/dist/esm-es5/mds-header-bar.entry.js +3 -3
- package/dist/esm-es5/mds-header.entry.js +8 -8
- 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 +4 -4
- package/dist/esm-es5/mds-input-date-range-preselection.entry.js +3 -3
- package/dist/esm-es5/mds-input-date-range.entry.js +48 -15
- package/dist/esm-es5/mds-input-date.entry.js +19 -10
- package/dist/esm-es5/mds-input-field.entry.js +4 -4
- package/dist/esm-es5/mds-input-otp.entry.js +6 -6
- package/dist/esm-es5/mds-input-range-value.entry.js +1 -0
- package/dist/esm-es5/mds-input-range.entry.js +93 -12
- package/dist/esm-es5/mds-input-select.entry.js +4 -4
- package/dist/esm-es5/mds-input-switch_2.entry.js +5 -5
- package/dist/esm-es5/mds-input-tip_2.entry.js +9 -6
- package/dist/esm-es5/mds-input-upload.entry.js +8 -8
- package/dist/esm-es5/mds-input.entry.js +157 -52
- package/dist/esm-es5/mds-keyboard-key.entry.js +2 -2
- package/dist/esm-es5/mds-keyboard.entry.js +7 -7
- package/dist/esm-es5/mds-kpi-item.entry.js +3 -3
- 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-link.entry.js +7 -7
- 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 +14 -14
- package/dist/esm-es5/mds-note.entry.js +3 -3
- package/dist/esm-es5/mds-notification.entry.js +8 -8
- package/dist/esm-es5/mds-paginator-item.entry.js +3 -3
- 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 +4 -4
- package/dist/esm-es5/mds-pref-consumption.entry.js +4 -4
- package/dist/esm-es5/mds-pref-contrast.entry.js +4 -4
- package/dist/esm-es5/mds-pref-language-item.entry.js +3 -3
- package/dist/esm-es5/mds-pref-language.entry.js +9 -9
- package/dist/esm-es5/mds-pref-mode.entry.js +7 -7
- package/dist/esm-es5/mds-pref-theme-item.entry.js +5 -5
- package/dist/esm-es5/mds-pref-theme.entry.js +14 -14
- package/dist/esm-es5/mds-pref.entry.js +7 -4
- 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 +2 -2
- package/dist/esm-es5/mds-price-table.entry.js +1 -1
- package/dist/esm-es5/mds-progress_2.entry.js +9 -5
- package/dist/esm-es5/mds-push-notification-item.entry.js +3 -3
- package/dist/esm-es5/mds-push-notification.entry.js +7 -7
- 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 +4 -4
- package/dist/esm-es5/mds-separator.entry.js +1 -1
- package/dist/esm-es5/mds-status-bar.entry.js +3 -3
- package/dist/esm-es5/mds-stepper-bar-item.entry.js +5 -5
- package/dist/esm-es5/mds-stepper-bar.entry.js +8 -5
- package/dist/esm-es5/mds-tab-bar-item.entry.js +4 -4
- package/dist/esm-es5/mds-tab-bar.entry.js +2 -2
- package/dist/esm-es5/mds-tab_2.entry.js +31 -11
- package/dist/esm-es5/mds-table-body.entry.js +1 -1
- package/dist/esm-es5/mds-table-footer.entry.js +2 -2
- package/dist/esm-es5/mds-table-header-cell.entry.js +7 -7
- package/dist/esm-es5/mds-table-header.entry.js +9 -8
- package/dist/esm-es5/mds-table-row.entry.js +4 -4
- package/dist/esm-es5/mds-table.entry.js +24 -11
- package/dist/esm-es5/mds-text.entry.js +7 -7
- package/dist/esm-es5/mds-toast-region.entry.js +5 -5
- package/dist/esm-es5/mds-toast.entry.js +7 -7
- package/dist/esm-es5/mds-tooltip.entry.js +12 -3
- package/dist/esm-es5/mds-tree-item.entry.js +7 -7
- package/dist/esm-es5/mds-tree.entry.js +5 -5
- package/dist/esm-es5/mds-url-view.entry.js +2 -2
- package/dist/esm-es5/mds-usage.entry.js +3 -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/{navigation-Bz1eiKqd.js → navigation-To9IeLHs.js} +8 -1
- package/dist/esm-es5/{preference-C8foBO86.js → preference-CBMLGSf7.js} +1 -1
- package/dist/hydrate/index.js +2097 -1008
- package/dist/hydrate/index.mjs +2097 -1008
- package/dist/magma-components/index.esm.js +1 -1
- package/dist/magma-components/magma-components.esm.js +1 -1
- package/dist/magma-components/magma-components.js +1 -1
- package/dist/magma-components/{p-c4c1ef48.system.entry.js → p-009e4359.system.entry.js} +118 -118
- package/dist/magma-components/{p-f0909679.system.entry.js → p-01d6d5a5.system.entry.js} +24 -11
- package/dist/magma-components/p-03285704.entry.js +1 -0
- package/dist/magma-components/p-03441f69.entry.js +1 -0
- package/dist/magma-components/p-03896fbd.entry.js +1 -0
- package/dist/magma-components/p-038fc1db.entry.js +1 -0
- package/dist/magma-components/{p-e3b9ea0b.system.entry.js → p-03a2f4e7.system.entry.js} +2 -2
- package/dist/magma-components/{p-caca78ff.system.entry.js → p-06ba1f71.system.entry.js} +4 -4
- package/dist/magma-components/p-0760e8a4.entry.js +1 -0
- package/dist/magma-components/p-082b787b.entry.js +1 -0
- package/dist/magma-components/p-09537867.entry.js +1 -0
- package/dist/magma-components/p-09675899.entry.js +1 -0
- package/dist/magma-components/p-0a914567.entry.js +1 -0
- package/dist/magma-components/p-0c8dd132.entry.js +1 -0
- package/dist/magma-components/p-0d7370d8.system.entry.js +1 -0
- package/dist/magma-components/{p-7a73fd19.system.entry.js → p-0e7bb90b.system.entry.js} +20 -20
- package/dist/magma-components/{p-dd348171.system.entry.js → p-10a68a4d.system.entry.js} +2 -2
- package/dist/magma-components/p-11312b0c.entry.js +1 -0
- package/dist/magma-components/{p-840c19ee.system.entry.js → p-11543f44.system.entry.js} +4 -4
- package/dist/magma-components/{p-3a836de8.system.entry.js → p-11ee7089.system.entry.js} +5 -5
- package/dist/magma-components/p-13e94501.entry.js +1 -0
- package/dist/magma-components/{p-c9baa3fb.system.entry.js → p-14f60718.system.entry.js} +1 -1
- package/dist/magma-components/p-16651356.entry.js +1 -0
- package/dist/magma-components/p-1686b36a.entry.js +1 -0
- package/dist/magma-components/{p-2e825656.system.entry.js → p-16a7e26a.system.entry.js} +4 -4
- package/dist/magma-components/p-1784d5fb.entry.js +1 -0
- package/dist/magma-components/p-18421a84.entry.js +1 -0
- package/dist/magma-components/p-1934151b.entry.js +1 -0
- package/dist/magma-components/p-193b58d0.entry.js +1 -0
- package/dist/magma-components/{p-720e9291.system.entry.js → p-19f3b524.system.entry.js} +6 -6
- package/dist/magma-components/{p-c54f2089.system.entry.js → p-1d101083.system.entry.js} +1 -1
- package/dist/magma-components/p-1db5ab39.entry.js +1 -0
- package/dist/magma-components/{p-24fb2c5c.system.entry.js → p-1e5d4854.system.entry.js} +7 -7
- package/dist/magma-components/p-1f756317.entry.js +1 -0
- package/dist/magma-components/p-2100343f.entry.js +1 -0
- package/dist/magma-components/p-211b2675.system.entry.js +1 -0
- package/dist/magma-components/{p-ca5427d4.system.entry.js → p-2289423c.system.entry.js} +1 -1
- package/dist/magma-components/p-26aad538.entry.js +1 -0
- package/dist/magma-components/p-270e9afa.entry.js +1 -0
- package/dist/magma-components/{p-9f0100f2.system.entry.js → p-275d7968.system.entry.js} +14 -14
- package/dist/magma-components/{p-5f20592f.system.entry.js → p-28ecae1e.system.entry.js} +2 -2
- package/dist/magma-components/{p-c94e7973.system.entry.js → p-2a5223df.system.entry.js} +7 -7
- package/dist/magma-components/p-2aa3e73a.system.entry.js +13 -0
- package/dist/magma-components/p-2c64ec7e.entry.js +1 -0
- package/dist/magma-components/{p-bcc6c358.system.entry.js → p-2dc9499c.system.entry.js} +3 -3
- package/dist/magma-components/{p-00d2ef14.system.entry.js → p-2dd32b3f.system.entry.js} +7 -7
- package/dist/magma-components/{p-380adee8.system.entry.js → p-2e5684a0.system.entry.js} +2 -2
- package/dist/magma-components/{p-390d0672.system.entry.js → p-303173d5.system.entry.js} +3 -3
- package/dist/magma-components/{p-7a4e8bc0.system.entry.js → p-33172d6f.system.entry.js} +8 -5
- package/dist/magma-components/p-333c0ae5.entry.js +1 -0
- package/dist/magma-components/p-3341ac50.entry.js +1 -0
- package/dist/magma-components/p-34183ce3.entry.js +1 -0
- package/dist/magma-components/p-35a77756.entry.js +1 -0
- package/dist/magma-components/p-37172440.entry.js +1 -0
- package/dist/magma-components/{p-3c911608.system.entry.js → p-37470fef.system.entry.js} +9 -5
- package/dist/magma-components/p-3b41f929.entry.js +1 -0
- package/dist/magma-components/p-3ccc1c10.entry.js +1 -0
- package/dist/magma-components/p-3d0578a7.entry.js +1 -0
- package/dist/magma-components/p-3d45d7a7.entry.js +1 -0
- package/dist/magma-components/{p-caf478ff.system.entry.js → p-3d60f528.system.entry.js} +2 -2
- package/dist/magma-components/p-3fb983e9.system.entry.js +1 -0
- package/dist/magma-components/p-4082973c.system.entry.js +30 -0
- package/dist/magma-components/p-41829c15.system.entry.js +7 -0
- package/dist/magma-components/p-420c5af4.entry.js +1 -0
- package/dist/magma-components/p-4242100c.entry.js +1 -0
- package/dist/magma-components/p-430239ca.entry.js +8 -0
- package/dist/magma-components/p-4564e7ad.entry.js +1 -0
- package/dist/magma-components/{p-6336d979.entry.js → p-47712df6.entry.js} +1 -1
- package/dist/magma-components/p-478bbfdb.entry.js +1 -0
- package/dist/magma-components/p-478e6930.entry.js +1 -0
- package/dist/magma-components/{p-c691f27e.system.entry.js → p-483480f9.system.entry.js} +31 -11
- package/dist/magma-components/p-4bb45501.entry.js +1 -0
- package/dist/magma-components/p-4e431466.entry.js +1 -0
- package/dist/magma-components/{p-1dc0d59c.system.entry.js → p-4e4dd1c1.system.entry.js} +5 -5
- package/dist/magma-components/{p-109926ce.system.entry.js → p-522968d1.system.entry.js} +6 -6
- package/dist/magma-components/{p-7e0a8194.system.entry.js → p-52b73a95.system.entry.js} +7 -7
- package/dist/magma-components/p-533bb401.system.entry.js +60 -0
- package/dist/magma-components/{p-9228db0b.system.entry.js → p-555bd3f8.system.entry.js} +7 -7
- package/dist/magma-components/{p-804f4794.system.entry.js → p-56715bbc.system.entry.js} +4 -4
- package/dist/magma-components/{p-527569a3.system.entry.js → p-586878a2.system.entry.js} +2 -2
- package/dist/magma-components/{p-3cf8ed46.system.entry.js → p-58bbada6.system.entry.js} +1 -1
- package/dist/magma-components/{p-eac943e5.system.entry.js → p-5b5d57b0.system.entry.js} +4 -4
- package/dist/magma-components/p-5c0f0517.entry.js +1 -0
- package/dist/magma-components/p-5c4aed7e.entry.js +1 -0
- package/dist/magma-components/p-5d8cb375.system.entry.js +107 -0
- package/dist/magma-components/p-62e42a62.entry.js +1 -0
- package/dist/magma-components/p-6443e40f.entry.js +1 -0
- package/dist/magma-components/{p-11456781.system.entry.js → p-6471c0a4.system.entry.js} +2 -2
- package/dist/magma-components/{p-b871ad36.system.entry.js → p-6619b3c0.system.entry.js} +11 -11
- package/dist/magma-components/p-67fa6fd7.entry.js +1 -0
- package/dist/magma-components/{p-79085c46.system.entry.js → p-68d83e18.system.entry.js} +1 -1
- package/dist/magma-components/{p-3ba14295.system.entry.js → p-6c6ec154.system.entry.js} +4 -4
- package/dist/magma-components/{p-8ac1ba5c.system.entry.js → p-6d7e8240.system.entry.js} +4 -4
- package/dist/magma-components/{p-3f0e6729.system.entry.js → p-6de384d0.system.entry.js} +3 -3
- package/dist/magma-components/p-6fb17347.system.entry.js +1 -0
- package/dist/magma-components/p-6fdf3b37.entry.js +1 -0
- package/dist/magma-components/p-70cf2c28.entry.js +1 -0
- package/dist/magma-components/p-73596a07.entry.js +1 -0
- package/dist/magma-components/{p-a5ca10ae.system.entry.js → p-73a6ee3b.system.entry.js} +1 -1
- package/dist/magma-components/{p-a9ab9eb0.system.entry.js → p-73b0b35f.system.entry.js} +2 -2
- package/dist/magma-components/p-73c0b53e.system.entry.js +82 -0
- package/dist/magma-components/p-73f22a7d.entry.js +1 -0
- package/dist/magma-components/p-756cd3dc.entry.js +1 -0
- package/dist/magma-components/p-757c3420.entry.js +1 -0
- package/dist/magma-components/p-778a46fa.entry.js +1 -0
- package/dist/magma-components/p-78cced59.entry.js +1 -0
- package/dist/magma-components/p-7caf244b.system.entry.js +7 -0
- package/dist/magma-components/p-7cfa2415.system.entry.js +1 -0
- package/dist/magma-components/p-7e87807d.entry.js +1 -0
- package/dist/magma-components/p-8193fd71.entry.js +1 -0
- package/dist/magma-components/p-82041de2.entry.js +1 -0
- package/dist/magma-components/{p-a2d4d849.system.entry.js → p-825713bc.system.entry.js} +2 -2
- package/dist/magma-components/p-851010c6.system.entry.js +25 -0
- package/dist/magma-components/p-857e893e.system.entry.js +26 -0
- package/dist/magma-components/p-8928d9b5.system.entry.js +110 -0
- package/dist/magma-components/p-8aa6524e.entry.js +1 -0
- package/dist/magma-components/p-8acbf50a.entry.js +1 -0
- package/dist/magma-components/p-8e471af5.entry.js +1 -0
- package/dist/magma-components/p-913123e6.entry.js +1 -0
- package/dist/magma-components/{p-724b7fff.system.entry.js → p-91406af1.system.entry.js} +9 -8
- package/dist/magma-components/p-95a29fd2.entry.js +1 -0
- package/dist/magma-components/{p-4a9ed4f7.system.entry.js → p-96ece2cc.system.entry.js} +4 -4
- package/dist/magma-components/p-96f66b8f.entry.js +1 -0
- package/dist/magma-components/{p-2a5167e3.system.entry.js → p-97e55f7e.system.entry.js} +5 -5
- package/dist/magma-components/{p-bc054fa3.system.entry.js → p-98a3802b.system.entry.js} +33 -18
- package/dist/magma-components/{p-0da5c696.system.entry.js → p-9b00051f.system.entry.js} +8 -8
- package/dist/magma-components/p-9be80c34.entry.js +1 -0
- package/dist/magma-components/{p-7701a318.system.entry.js → p-9c0d1025.system.entry.js} +1 -1
- package/dist/magma-components/{p-6f90c2c9.system.entry.js → p-9e3c1c28.system.entry.js} +9 -9
- package/dist/magma-components/{p-BoDvZoCN.system.js → p-B6f9M1Bj.system.js} +8 -1
- package/dist/magma-components/p-B7Jp0tqu.system.js +5 -0
- package/dist/magma-components/p-BAW1DAbr.system.js +13 -0
- package/dist/magma-components/{p-nFkaC8l_.system.js → p-BAcul0Zt.system.js} +1 -1
- package/dist/magma-components/{p-DxR4rGsw.js → p-BXkIXROP.js} +1 -1
- package/dist/magma-components/{p-CATyfc78.js → p-BkfGbFba.js} +2 -2
- package/dist/magma-components/{p-BaFfIZGB.js → p-C7p9e0P3.js} +1 -1
- package/dist/magma-components/p-CPibDZjX.js +3 -0
- package/dist/magma-components/{p-Cbabyppz.system.js → p-CyPLJo0p.system.js} +34 -14
- package/dist/magma-components/{p-BHdlb7Fr.system.js → p-CzZWts7L.system.js} +8 -8
- package/dist/magma-components/{p-VOjLCGlK.system.js → p-D5Yayq7E.system.js} +47 -5
- package/dist/magma-components/{p-DOisMne4.system.js → p-DGfoeZMw.system.js} +6 -6
- package/dist/magma-components/{p-BZP13mns.system.js → p-EhfbAdzV.system.js} +52 -51
- package/dist/magma-components/p-H8sVzFTL.js +1 -0
- package/dist/magma-components/p-a00805cd.system.entry.js +136 -0
- package/dist/magma-components/p-a025b35b.entry.js +1 -0
- package/dist/magma-components/p-a02819e3.entry.js +1 -0
- package/dist/magma-components/p-a0389821.entry.js +1 -0
- package/dist/magma-components/p-a075c069.entry.js +1 -0
- package/dist/magma-components/p-a0764f01.entry.js +1 -0
- package/dist/magma-components/{p-54abba52.system.entry.js → p-a171c096.system.entry.js} +4 -4
- package/dist/magma-components/{p-9b0b65f0.system.entry.js → p-a190c325.system.entry.js} +3 -3
- package/dist/magma-components/{p-f2649031.entry.js → p-a33a235e.entry.js} +1 -1
- package/dist/magma-components/{p-7fbdf896.system.entry.js → p-a4aaf1c6.system.entry.js} +8 -8
- package/dist/magma-components/{p-c8c918d2.entry.js → p-a9c7fb3f.entry.js} +3 -3
- package/dist/magma-components/{p-372fa5d4.system.entry.js → p-a9d100e5.system.entry.js} +7 -7
- package/dist/magma-components/{p-09a7c1de.system.entry.js → p-aa601247.system.entry.js} +2 -2
- package/dist/magma-components/{p-ca4e8601.system.entry.js → p-aa86018e.system.entry.js} +2 -2
- package/dist/magma-components/p-ab920e0b.entry.js +1 -0
- package/dist/magma-components/{p-f51ed098.entry.js → p-ac401f1a.entry.js} +1 -1
- package/dist/magma-components/{p-f5bd5b64.system.entry.js → p-ad12fa89.system.entry.js} +3 -3
- package/dist/magma-components/{p-3ddae677.system.entry.js → p-ad6b5fc1.system.entry.js} +3 -3
- package/dist/magma-components/p-ada93f68.entry.js +1 -0
- package/dist/magma-components/{p-4a72d72c.system.entry.js → p-ae258eca.system.entry.js} +2 -2
- package/dist/magma-components/{p-a48c73b1.system.entry.js → p-af1a93c6.system.entry.js} +7 -7
- package/dist/magma-components/p-b0406c51.entry.js +1 -0
- package/dist/magma-components/p-b18b0088.system.entry.js +9 -0
- package/dist/magma-components/p-b1fe6261.entry.js +1 -0
- package/dist/magma-components/{p-99d2ace2.system.entry.js → p-b47c444e.system.entry.js} +2 -2
- package/dist/magma-components/p-b4856322.entry.js +1 -0
- package/dist/magma-components/p-b7d90310.entry.js +1 -0
- package/dist/magma-components/{p-0e1d239b.system.entry.js → p-b8e5411d.system.entry.js} +1 -1
- package/dist/magma-components/{p-4a2ed30e.system.entry.js → p-b95f648f.system.entry.js} +3 -3
- package/dist/magma-components/{p-64f86e46.system.entry.js → p-ba148b89.system.entry.js} +7 -7
- package/dist/magma-components/p-bbbf8b89.system.entry.js +29 -0
- package/dist/magma-components/p-bca909d9.entry.js +1 -0
- package/dist/magma-components/p-bd4ad8c7.entry.js +1 -0
- package/dist/magma-components/p-bd539dbc.entry.js +1 -0
- package/dist/magma-components/{p-f7e9af99.system.entry.js → p-c0c69807.system.entry.js} +2 -2
- package/dist/magma-components/{p-22f24125.system.entry.js → p-c2a883b0.system.entry.js} +1 -1
- package/dist/magma-components/{p-b7d18d7a.system.entry.js → p-c2d9cf4e.system.entry.js} +1 -1
- package/dist/magma-components/{p-555ba0e0.system.entry.js → p-c3cfbc71.system.entry.js} +8 -8
- package/dist/magma-components/p-c5b7f820.system.entry.js +1 -0
- package/dist/magma-components/p-c67655fa.entry.js +1 -0
- package/dist/magma-components/p-c6cab2cb.entry.js +1 -0
- package/dist/magma-components/p-c6f56934.entry.js +1 -0
- package/dist/magma-components/{p-793072e1.system.entry.js → p-c8430552.system.entry.js} +14 -14
- package/dist/magma-components/p-c902d468.entry.js +1 -0
- package/dist/magma-components/p-ca0f3549.entry.js +1 -0
- package/dist/magma-components/{p-98cc6473.system.entry.js → p-ca5867f5.system.entry.js} +15 -15
- package/dist/magma-components/p-cc5518b1.entry.js +1 -0
- package/dist/magma-components/{p-32b3ad6f.entry.js → p-ccb23b6a.entry.js} +1 -1
- package/dist/magma-components/p-ccb64689.system.entry.js +113 -0
- package/dist/magma-components/{p-fe51c0cb.system.entry.js → p-cf8cfcac.system.entry.js} +3 -3
- package/dist/magma-components/p-cfb153b8.entry.js +1 -0
- package/dist/magma-components/p-cfcb8bb5.entry.js +1 -0
- package/dist/magma-components/p-d0b45a54.entry.js +1 -0
- package/dist/magma-components/{p-3f17a06f.system.entry.js → p-d0dfa8b5.system.entry.js} +2 -2
- package/dist/magma-components/p-d1281855.system.entry.js +330 -0
- package/dist/magma-components/{p-48a1871f.system.entry.js → p-d173ae2f.system.entry.js} +1 -1
- package/dist/magma-components/p-d1751ff6.entry.js +1 -0
- package/dist/magma-components/p-d32ca6ce.entry.js +1 -0
- package/dist/magma-components/p-d4452e41.entry.js +1 -0
- package/dist/magma-components/p-d5dec64d.entry.js +1 -0
- package/dist/magma-components/p-d7813f9b.system.entry.js +13 -0
- package/dist/magma-components/{p-27a32865.system.entry.js → p-dd4b04ed.system.entry.js} +3 -3
- package/dist/magma-components/p-ddc31c50.entry.js +1 -0
- package/dist/magma-components/{p-b129b127.system.entry.js → p-df70af5f.system.entry.js} +37 -37
- package/dist/magma-components/p-e009c632.entry.js +1 -0
- package/dist/magma-components/p-e160e4e1.entry.js +1 -0
- package/dist/magma-components/p-e497f0db.entry.js +1 -0
- package/dist/magma-components/p-e4db9ad2.entry.js +1 -0
- package/dist/magma-components/p-e63c1ba4.entry.js +1 -0
- package/dist/magma-components/p-e66db408.entry.js +1 -0
- package/dist/magma-components/{p-5c6fdabd.system.entry.js → p-e84361ee.system.entry.js} +12 -3
- package/dist/magma-components/p-ea93721d.entry.js +1 -0
- package/dist/magma-components/{p-f6358241.system.entry.js → p-eb4f76d8.system.entry.js} +9 -6
- package/dist/magma-components/p-ecf29ffa.entry.js +1 -0
- package/dist/magma-components/{p-5794053b.system.entry.js → p-ede31d27.system.entry.js} +6 -6
- package/dist/magma-components/{p-66f7f9b1.system.entry.js → p-ee247029.system.entry.js} +3 -3
- package/dist/magma-components/{p-45c26a24.system.entry.js → p-ee65f0eb.system.entry.js} +5 -5
- package/dist/magma-components/p-efcd8a1d.entry.js +1 -0
- package/dist/magma-components/{p-9b0d7f7d.system.entry.js → p-f01e7a7e.system.entry.js} +4 -4
- package/dist/magma-components/{p-188a55ac.system.entry.js → p-f0d93b22.system.entry.js} +9 -6
- package/dist/magma-components/{p-c0295a0e.system.entry.js → p-f2e5a2c7.system.entry.js} +7 -7
- package/dist/magma-components/p-f3041712.entry.js +1 -0
- package/dist/magma-components/{p-97a501cd.system.entry.js → p-f3f1da06.system.entry.js} +5 -5
- package/dist/magma-components/{p-b1cd3acf.system.entry.js → p-f4e8f507.system.entry.js} +2 -2
- package/dist/magma-components/{p-1e24aafa.system.entry.js → p-f5c82548.system.entry.js} +1 -1
- package/dist/magma-components/{p-411fca2f.system.entry.js → p-f6f6d914.system.entry.js} +3 -3
- package/dist/magma-components/p-f9d2316a.entry.js +1 -0
- package/dist/magma-components/p-fe4ae251.entry.js +1 -0
- package/dist/magma-components/{p-16bbff4e.system.entry.js → p-ffcfa9e3.system.entry.js} +2 -2
- package/dist/magma-components/p-kW8cjKIa.js +1 -0
- package/dist/mcp/checks.js +1 -1
- package/dist/stats.json +4106 -3337
- package/dist/types/common/floating-controller.d.ts +14 -0
- package/dist/types/common/navigation.d.ts +7 -0
- package/dist/types/common/preference.d.ts +13 -1
- package/dist/types/common/validity/index.d.ts +1 -1
- package/dist/types/components/mds-accordion-item/mds-accordion-item.d.ts +10 -2
- package/dist/types/components/mds-accordion-timer-item/mds-accordion-timer-item.d.ts +10 -2
- package/dist/types/components/mds-banner/mds-banner.d.ts +13 -4
- package/dist/types/components/mds-banner/meta/dictionary.d.ts +7 -0
- package/dist/types/components/mds-banner/meta/types.d.ts +2 -0
- package/dist/types/components/mds-calendar/mds-calendar.d.ts +60 -16
- package/dist/types/components/mds-calendar/meta/types.d.ts +2 -0
- package/dist/types/components/mds-chip/mds-chip.d.ts +10 -0
- package/dist/types/components/mds-dropdown/mds-dropdown.d.ts +1 -0
- package/dist/types/components/mds-icon/services/icons-set.service.d.ts +42 -0
- package/dist/types/components/mds-input/mds-input.d.ts +114 -10
- package/dist/types/components/mds-input/meta/color.d.ts +13 -0
- package/dist/types/components/mds-input/meta/types.d.ts +1 -1
- package/dist/types/components/mds-input/meta/validators.d.ts +5 -0
- package/dist/types/components/mds-input/meta/validity.d.ts +3 -2
- package/dist/types/components/mds-input-date/mds-input-date.d.ts +13 -2
- package/dist/types/components/mds-input-date-range/mds-input-date-range.d.ts +34 -3
- package/dist/types/components/mds-input-range/mds-input-range.d.ts +96 -4
- package/dist/types/components/mds-input-range/meta/event-detail.d.ts +7 -0
- package/dist/types/components/mds-input-range-value/mds-input-range-value.d.ts +18 -0
- package/dist/types/components/mds-input-tip/mds-input-tip.d.ts +6 -3
- package/dist/types/components/mds-input-tip-item/meta/dictionary.d.ts +1 -1
- package/dist/types/components/mds-pref/mds-pref.d.ts +6 -0
- package/dist/types/components/mds-tab/mds-tab.d.ts +2 -1
- package/dist/types/components/mds-table/mds-table.d.ts +6 -1
- package/dist/types/components/mds-table-header/mds-table-header.d.ts +1 -1
- package/dist/types/components/mds-url-view/mds-url-view.d.ts +0 -3
- package/dist/types/components/mds-zero/mds-zero.d.ts +4 -0
- package/dist/types/components.d.ts +157 -38
- package/dist/types/fixtures/dark-mode.d.ts +7 -0
- package/dist/types/index.d.ts +20 -8
- package/dist/types/stencil-public-runtime.d.ts +1 -1
- package/dist/types/type/file-types.d.ts +1 -1
- package/dist/types/type/input.d.ts +2 -2
- package/package.json +19 -17
- package/dist/components/p-BQSO-HFx.js +0 -1
- package/dist/components/p-Bw-eI2ca.js +0 -1
- package/dist/components/p-BwwiliWt.js +0 -1
- package/dist/components/p-CZX6N7ce.js +0 -1
- package/dist/components/p-CpuUmvdl.js +0 -1
- package/dist/components/p-DUgCzZw9.js +0 -1
- package/dist/components/p-DWOg4-dH.js +0 -1
- package/dist/components/p-DZ4_zLTp.js +0 -1
- package/dist/components/p-J48g0t65.js +0 -1
- package/dist/components/p-TZJN-ygm.js +0 -3
- package/dist/components/p-UfaGafRS.js +0 -1
- package/dist/components/p-k_Ly95Tj.js +0 -1
- package/dist/components/p-lXKBo6V3.js +0 -1
- package/dist/components/p-oFHbHRLX.js +0 -1
- package/dist/esm-es5/index-DEL0bLpb.js +0 -10
- package/dist/magma-components/p-02aed12a.entry.js +0 -1
- package/dist/magma-components/p-0417391b.entry.js +0 -1
- package/dist/magma-components/p-08f7a84b.entry.js +0 -1
- package/dist/magma-components/p-0df067b4.entry.js +0 -1
- package/dist/magma-components/p-0f4c2de6.entry.js +0 -1
- package/dist/magma-components/p-14de26d5.entry.js +0 -1
- package/dist/magma-components/p-163eccbd.entry.js +0 -1
- package/dist/magma-components/p-167ba07a.entry.js +0 -1
- package/dist/magma-components/p-17249b74.entry.js +0 -1
- package/dist/magma-components/p-1a53d9d0.system.entry.js +0 -225
- package/dist/magma-components/p-1cc379d6.entry.js +0 -1
- package/dist/magma-components/p-223efc32.entry.js +0 -1
- package/dist/magma-components/p-2454e4cd.system.entry.js +0 -7
- package/dist/magma-components/p-24a69c45.entry.js +0 -1
- package/dist/magma-components/p-259d9380.entry.js +0 -1
- package/dist/magma-components/p-26b08e33.entry.js +0 -1
- package/dist/magma-components/p-2940499f.entry.js +0 -1
- package/dist/magma-components/p-2f4a7253.system.entry.js +0 -1
- package/dist/magma-components/p-2ffa4d4a.entry.js +0 -1
- package/dist/magma-components/p-33129e0c.system.entry.js +0 -13
- package/dist/magma-components/p-397c0686.entry.js +0 -1
- package/dist/magma-components/p-3bf4f012.system.entry.js +0 -13
- package/dist/magma-components/p-3de37b32.entry.js +0 -1
- package/dist/magma-components/p-40c59c18.entry.js +0 -1
- package/dist/magma-components/p-43c307f5.entry.js +0 -1
- package/dist/magma-components/p-440d7942.entry.js +0 -1
- package/dist/magma-components/p-4541c233.entry.js +0 -1
- package/dist/magma-components/p-4612bc78.entry.js +0 -8
- package/dist/magma-components/p-4718a71d.entry.js +0 -1
- package/dist/magma-components/p-4a1f7eb5.entry.js +0 -1
- package/dist/magma-components/p-4c3b3913.system.entry.js +0 -25
- package/dist/magma-components/p-4c955367.entry.js +0 -1
- package/dist/magma-components/p-4ebb0a9e.entry.js +0 -1
- package/dist/magma-components/p-4f80bf37.entry.js +0 -1
- package/dist/magma-components/p-52211fa3.entry.js +0 -1
- package/dist/magma-components/p-52cc5a93.entry.js +0 -1
- package/dist/magma-components/p-56cf1cab.entry.js +0 -1
- package/dist/magma-components/p-59aa4994.entry.js +0 -1
- package/dist/magma-components/p-5a754d7b.entry.js +0 -1
- package/dist/magma-components/p-5ca6063a.entry.js +0 -1
- package/dist/magma-components/p-5cb581df.entry.js +0 -1
- package/dist/magma-components/p-5d825728.entry.js +0 -1
- package/dist/magma-components/p-5dfca9f0.entry.js +0 -1
- package/dist/magma-components/p-5f38e95b.entry.js +0 -1
- package/dist/magma-components/p-5f4bec31.entry.js +0 -1
- package/dist/magma-components/p-627f5956.entry.js +0 -1
- package/dist/magma-components/p-6352c2ea.entry.js +0 -1
- package/dist/magma-components/p-64884d84.entry.js +0 -1
- package/dist/magma-components/p-65ea6fc9.entry.js +0 -1
- package/dist/magma-components/p-68b0d45a.entry.js +0 -1
- package/dist/magma-components/p-6a4d44e2.entry.js +0 -1
- package/dist/magma-components/p-6a90caf5.system.entry.js +0 -1
- package/dist/magma-components/p-6c4f2de0.entry.js +0 -1
- package/dist/magma-components/p-70faf379.entry.js +0 -1
- package/dist/magma-components/p-71d03e56.entry.js +0 -1
- package/dist/magma-components/p-73dc7c66.entry.js +0 -1
- package/dist/magma-components/p-7476cf76.system.entry.js +0 -77
- package/dist/magma-components/p-77707706.entry.js +0 -1
- package/dist/magma-components/p-78d00f88.entry.js +0 -1
- package/dist/magma-components/p-79392a0a.entry.js +0 -1
- package/dist/magma-components/p-7a33ab3c.entry.js +0 -1
- package/dist/magma-components/p-7b552dbe.entry.js +0 -1
- package/dist/magma-components/p-7c13ccb0.entry.js +0 -1
- package/dist/magma-components/p-848d1b42.system.entry.js +0 -30
- package/dist/magma-components/p-84d0d701.entry.js +0 -1
- package/dist/magma-components/p-86494ea9.entry.js +0 -1
- package/dist/magma-components/p-8915347f.entry.js +0 -1
- package/dist/magma-components/p-8b8a6662.entry.js +0 -1
- package/dist/magma-components/p-8c20ac0c.entry.js +0 -1
- package/dist/magma-components/p-90c60c48.entry.js +0 -1
- package/dist/magma-components/p-90e20ad3.entry.js +0 -1
- package/dist/magma-components/p-94548d43.entry.js +0 -1
- package/dist/magma-components/p-95020326.entry.js +0 -1
- package/dist/magma-components/p-970f45df.entry.js +0 -1
- package/dist/magma-components/p-9aba3769.entry.js +0 -1
- package/dist/magma-components/p-9b8d15a8.system.entry.js +0 -1
- package/dist/magma-components/p-9e94f4a3.system.entry.js +0 -41
- package/dist/magma-components/p-B8zYiZQY.system.js +0 -5
- package/dist/magma-components/p-CvLLN-QH.js +0 -3
- package/dist/magma-components/p-CxzVgcYv.js +0 -1
- package/dist/magma-components/p-D3J9KZKy.system.js +0 -10
- package/dist/magma-components/p-Dx7iOdVP.js +0 -1
- package/dist/magma-components/p-a112a0e2.system.entry.js +0 -24
- package/dist/magma-components/p-a2767235.entry.js +0 -1
- package/dist/magma-components/p-a2c3b294.system.entry.js +0 -94
- package/dist/magma-components/p-a4f53c83.entry.js +0 -1
- package/dist/magma-components/p-a58e8a5c.entry.js +0 -1
- package/dist/magma-components/p-a9a872e1.entry.js +0 -1
- package/dist/magma-components/p-ab1c3fb0.system.entry.js +0 -7
- package/dist/magma-components/p-ab445c2b.entry.js +0 -1
- package/dist/magma-components/p-abe32d5b.entry.js +0 -1
- package/dist/magma-components/p-af56e3e4.system.entry.js +0 -32
- package/dist/magma-components/p-b1238d48.entry.js +0 -1
- package/dist/magma-components/p-b705b805.entry.js +0 -1
- package/dist/magma-components/p-ba871d9c.entry.js +0 -1
- package/dist/magma-components/p-ba95bf93.entry.js +0 -1
- package/dist/magma-components/p-bd489df9.entry.js +0 -1
- package/dist/magma-components/p-bfd95736.entry.js +0 -1
- package/dist/magma-components/p-c06d8b5a.entry.js +0 -1
- package/dist/magma-components/p-c131d726.entry.js +0 -1
- package/dist/magma-components/p-c2758b81.entry.js +0 -1
- package/dist/magma-components/p-c49676e6.entry.js +0 -1
- package/dist/magma-components/p-c8414ee6.entry.js +0 -1
- package/dist/magma-components/p-c91cb63a.entry.js +0 -1
- package/dist/magma-components/p-cb06839f.entry.js +0 -1
- package/dist/magma-components/p-ce42734f.entry.js +0 -1
- package/dist/magma-components/p-d1e4a032.entry.js +0 -1
- package/dist/magma-components/p-d25a47fa.entry.js +0 -1
- package/dist/magma-components/p-d29b32b4.system.entry.js +0 -1
- package/dist/magma-components/p-d2ba5851.system.entry.js +0 -82
- package/dist/magma-components/p-d365c6b6.entry.js +0 -1
- package/dist/magma-components/p-d3b06151.entry.js +0 -1
- package/dist/magma-components/p-d45f65e0.entry.js +0 -1
- package/dist/magma-components/p-d51ec950.entry.js +0 -1
- package/dist/magma-components/p-d760c1fa.entry.js +0 -1
- package/dist/magma-components/p-d785d7ee.entry.js +0 -1
- package/dist/magma-components/p-d9092133.entry.js +0 -1
- package/dist/magma-components/p-de423b11.entry.js +0 -1
- package/dist/magma-components/p-df78b7ac.system.entry.js +0 -1
- package/dist/magma-components/p-e39b5e12.entry.js +0 -1
- package/dist/magma-components/p-eb220deb.system.entry.js +0 -7
- package/dist/magma-components/p-eca42fe8.system.entry.js +0 -29
- package/dist/magma-components/p-ecda3e45.entry.js +0 -1
- package/dist/magma-components/p-f9f3ad86.entry.js +0 -1
- package/dist/magma-components/p-fb4b648a.entry.js +0 -1
- package/dist/magma-components/p-fd4588c5.entry.js +0 -1
- package/dist/magma-components/p-fdd17ee6.entry.js +0 -1
- package/dist/magma-components/p-ff6cf4f8.system.entry.js +0 -98
- package/dist/magma-components/p-ff76c614.entry.js +0 -1
- /package/dist/components/{p-Bz1eiKqd.js → p-To9IeLHs.js} +0 -0
- /package/dist/magma-components/{p-Bz1eiKqd.js → p-To9IeLHs.js} +0 -0
package/dist/documentation.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
|
-
"timestamp": "2026-11-
|
|
2
|
+
"timestamp": "2026-11-12T09:55:22",
|
|
3
3
|
"compiler": {
|
|
4
4
|
"name": "@stencil/core",
|
|
5
|
-
"version": "4.45.
|
|
5
|
+
"version": "4.45.3",
|
|
6
6
|
"typescriptVersion": "5.8.3"
|
|
7
7
|
},
|
|
8
8
|
"components": [
|
|
@@ -23,8 +23,8 @@
|
|
|
23
23
|
}
|
|
24
24
|
],
|
|
25
25
|
"usage": {
|
|
26
|
-
"1. Description": "The `<mds-accordion>` web component is the compound container of the Magma Design System that groups and orchestrates a set of collapsible `<mds-accordion-item>` panels. It acts as the coordination layer that decides which children are selected.\n\n#### Semantic Behavior\n\n- **Compound parent/child**: The default slot accepts only `<mds-accordion-item>` elements.\n- **Single vs. multiple selection**: By default opening one item collapses the others. With `multiple` set, any number of children may stay open at once and selection state is reported as a comma-separated list of indices.\n- **Mandatory selection**: When `disable-close` is set, the user cannot collapse the currently open item by clicking it again - one panel always remains open.\n- **Emitted event**: `mdsAccordionChange` once for every change of the open items, opening and closing alike, carrying the live `children` NodeList and the `selected` index/indices as a string (empty when none is open). A click that `disable-close` turns down changes nothing and emits nothing.\n\n#### Properties & Visual Configurations\n\nThis component has no shared `variant` / `tone` / `size` props; its two booleans control selection semantics rather than appearance.\n\n#### Other behavioral props\n\n- **`multiple`** switches the group from accordion behavior (one panel at a time) to independent toggles, allowing several panels open simultaneously.\n- **`disableClose`** prevents the active panel from being dismissed; set it to force at least one panel to stay expanded at all times.\n\nPer-panel presentation - the visible `label`, the title style `typography`, and the slotted body content - is configured on each `<mds-accordion-item>` child, not on the accordion itself.\n",
|
|
27
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-accordion>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Accordion\n\nThe canonical form. Place one or more [`mds-accordion-item`](../mds-accordion-item/AGENTS.md) elements as direct children. Each item requires a `label` for its always-visible header.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Informazioni generali\">\n <mds-text>Contenuto della prima sezione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Requisiti tecnici\">\n <mds-text>Contenuto della seconda sezione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Contatti\">\n <mds-text>Contenuto della terza sezione.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Pre-selected Item on Load\n\nSet the `selected` attribute on a child to have that panel start open. Only one item should be pre-selected in single-selection mode (the default).\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Panoramica\" selected>\n <mds-text>Questa sezione e' aperta per impostazione predefinita.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Dettagli\">\n <mds-text>Questa sezione e' chiusa inizialmente.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Multiple Selection Mode\n\nSet `multiple` to allow any number of panels to be open at the same time. The `mdsAccordionChange` event then reports a comma-separated list of open indices.\n\n```html\n<mds-accordion multiple>\n <mds-accordion-item label=\"Documentazione\" selected>\n <mds-text>Scarica la guida utente in formato PDF.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Video tutorial\" selected>\n <mds-text>Guarda i video di formazione nel portale.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"FAQ\">\n <mds-text>Consulta le domande frequenti.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Mandatory Selection (Non-closable)\n\nSet `disable-close` to prevent the open panel from being collapsed. The currently expanded item stays open even when the user clicks its header again - exactly one panel is always visible.\n\n```html\n<mds-accordion disable-close>\n <mds-accordion-item label=\"Passaggio 1 - Dati anagrafici\" selected>\n <mds-text>Inserisci nome, cognome e codice fiscale.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Passaggio 2 - Residenza\">\n <mds-text>Inserisci indirizzo e comune di residenza.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Passaggio 3 - Riepilogo\">\n <mds-text>Verifica i dati inseriti prima di inviare.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### A Title Above, Parts Inside\n\nThe accordion stands under the title of its section, written by its role; each item is a part, whose title is styled as `h6` (`titles/part`): write `typography=\"h6\"` until the default moves from `h5` with the next major (#1218).
|
|
26
|
+
"1. Description": "The `<mds-accordion>` web component is the compound container of the Magma Design System that groups and orchestrates a set of collapsible `<mds-accordion-item>` panels. It acts as the coordination layer that decides which children are selected.\n\n#### Semantic Behavior\n\n- **Compound parent/child**: The default slot accepts only `<mds-accordion-item>` elements.\n- **Single vs. multiple selection**: By default opening one item collapses the others. With `multiple` set, any number of children may stay open at once and selection state is reported as a comma-separated list of indices.\n- **Mandatory selection**: When `disable-close` is set, the user cannot collapse the currently open item by clicking it again - one panel always remains open.\n- **Emitted event**: `mdsAccordionChange` once for every change of the open items, opening and closing alike, carrying the live `children` NodeList and the `selected` index/indices as a string (empty when none is open). A click that `disable-close` turns down changes nothing and emits nothing.\n\n#### Properties & Visual Configurations\n\nThis component has no shared `variant` / `tone` / `size` props; its two booleans control selection semantics rather than appearance.\n\n#### Other behavioral props\n\n- **`multiple`** switches the group from accordion behavior (one panel at a time) to independent toggles, allowing several panels open simultaneously.\n- **`disableClose`** prevents the active panel from being dismissed; set it to force at least one panel to stay expanded at all times.\n\nPer-panel presentation - the visible `label`, the title style `typography`, the level `tag` of the title in the outline of the page, and the slotted body content - is configured on each `<mds-accordion-item>` child, not on the accordion itself.\n",
|
|
27
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-accordion>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Accordion\n\nThe canonical form. Place one or more [`mds-accordion-item`](../mds-accordion-item/AGENTS.md) elements as direct children. Each item requires a `label` for its always-visible header.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Informazioni generali\">\n <mds-text>Contenuto della prima sezione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Requisiti tecnici\">\n <mds-text>Contenuto della seconda sezione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Contatti\">\n <mds-text>Contenuto della terza sezione.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Pre-selected Item on Load\n\nSet the `selected` attribute on a child to have that panel start open. Only one item should be pre-selected in single-selection mode (the default).\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Panoramica\" selected>\n <mds-text>Questa sezione e' aperta per impostazione predefinita.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Dettagli\">\n <mds-text>Questa sezione e' chiusa inizialmente.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Multiple Selection Mode\n\nSet `multiple` to allow any number of panels to be open at the same time. The `mdsAccordionChange` event then reports a comma-separated list of open indices.\n\n```html\n<mds-accordion multiple>\n <mds-accordion-item label=\"Documentazione\" selected>\n <mds-text>Scarica la guida utente in formato PDF.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Video tutorial\" selected>\n <mds-text>Guarda i video di formazione nel portale.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"FAQ\">\n <mds-text>Consulta le domande frequenti.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Mandatory Selection (Non-closable)\n\nSet `disable-close` to prevent the open panel from being collapsed. The currently expanded item stays open even when the user clicks its header again - exactly one panel is always visible.\n\n```html\n<mds-accordion disable-close>\n <mds-accordion-item label=\"Passaggio 1 - Dati anagrafici\" selected>\n <mds-text>Inserisci nome, cognome e codice fiscale.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Passaggio 2 - Residenza\">\n <mds-text>Inserisci indirizzo e comune di residenza.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Passaggio 3 - Riepilogo\">\n <mds-text>Verifica i dati inseriti prima di inviare.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### A Title Above, Parts Inside\n\nThe accordion stands under the title of its section, written by its role; each item is a part, whose title is styled as `h6` (`titles/part`): write `typography=\"h6\"` until the default moves from `h5` with the next major (#1218). `typography` is the style of an item; its `tag` is the level in the outline, one below the title of the section (`h3` under an `h2`), and the heading wraps the button that opens the item, as the Accordion pattern of the WAI-ARIA Authoring Practices does.\n\n```html\n<mds-text typography=\"section\" tag=\"h2\">Documenti richiesti</mds-text>\n<mds-accordion>\n <mds-accordion-item label=\"Documento di identita'\" typography=\"h6\" tag=\"h3\">\n <mds-text>Carta d'identita' o passaporto in corso di validita'.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Codice fiscale\" typography=\"h6\" tag=\"h3\">\n <mds-text>La tessera sanitaria o il certificato di attribuzione.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Listening to the Change Event\n\nListen for `mdsAccordionChange` to react when the active panel changes. The event detail carries `children` (the full NodeList) and `selected` (a string index or comma-separated indices when `multiple` is set).\n\n```html\n<mds-accordion id=\"faq-accordion\">\n <mds-accordion-item label=\"Cos'e' Magma?\">\n <mds-text>Magma e' il design system di Maggioli.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Come si installa?\">\n <mds-text>Segui le istruzioni nel file README del pacchetto.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n\n<script>\n document.getElementById('faq-accordion').addEventListener('mdsAccordionChange', (event) => {\n console.log('Pannello aperto:', event.detail.selected);\n });\n</script>\n```\n\n#### Rich Slotted Content in Items\n\nThe default slot of each `mds-accordion-item` accepts text, HTML elements, and other Magma components - use this to build complex content panels.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Dettagli del documento\">\n <mds-text typography=\"label\">Nome file</mds-text>\n <mds-text>Relazione_annuale_2024.pdf</mds-text>\n <mds-hr></mds-hr>\n <mds-text typography=\"label\">Dimensione</mds-text>\n <mds-text>2,4 MB</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Azioni disponibili\">\n <mds-button label=\"Scarica\" icon=\"mi/baseline/download\" variant=\"primary\"></mds-button>\n <mds-button label=\"Condividi\" icon=\"mi/baseline/share\" variant=\"primary\" tone=\"outline\"></mds-button>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Styling Customization\n\nStyle the accordion only through its public `--mds-accordion-*` CSS custom properties. The properties cascade into all child `mds-accordion-item` elements from the host.\n\n```css\n.custom-faq mds-accordion {\n --mds-accordion-color: rgb(var(--magma-text-default));\n --mds-accordion-padding-selected: calc(var(--spacing) * 600) 0 calc(var(--spacing) * 800) 0;\n --mds-accordion-padding-unselected: calc(var(--spacing) * 400) 0;\n}\n```\n",
|
|
28
28
|
"3. Mistakes": "Common incorrect uses of `<mds-accordion>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Place Non-Item Children Directly in the Accordion Slot\n\nThe default slot of `<mds-accordion>` is designed exclusively for `<mds-accordion-item>` elements. Placing raw HTML or other components there bypasses the parent's selection coordination and breaks the compound component communication.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion>\n <div>\n <h3>Sezione uno</h3>\n <p>Contenuto della sezione.</p>\n </div>\n</mds-accordion>\n\n<!-- CORRECT -->\n<mds-accordion>\n <mds-accordion-item label=\"Sezione uno\">\n <mds-text>Contenuto della sezione.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Use `mds-accordion-item` Outside `mds-accordion`\n\n`<mds-accordion-item>` is a compound child and relies on the parent to give it an `id` when it has none and to manage selection state. Used standalone it has no coordinator and its `mdsAccordionItemSelect` / `mdsAccordionItemUnselect` events go unanswered.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion-item label=\"Domanda frequente\">\n <mds-text>Risposta alla domanda.</mds-text>\n</mds-accordion-item>\n\n<!-- CORRECT -->\n<mds-accordion>\n <mds-accordion-item label=\"Domanda frequente\">\n <mds-text>Risposta alla domanda.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Listen to Native `click` or `toggle` Instead of `mdsAccordionChange`\n\nA native `click` bubbles up from anywhere inside the accordion, panel content included, and carries no selection state; there is no native `toggle` event on this component. Listen for `mdsAccordionChange`, whose `detail.selected` holds the open index/indices.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion id=\"my-accordion\">\n <mds-accordion-item label=\"Sezione A\">\n <mds-text>Contenuto A.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n<script>\n document.getElementById('my-accordion').addEventListener('click', (e) => {\n // fires on any click, panel content included, and says nothing about the selection\n console.log('clicked');\n });\n</script>\n\n<!-- CORRECT -->\n<mds-accordion id=\"my-accordion\">\n <mds-accordion-item label=\"Sezione A\">\n <mds-text>Contenuto A.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n<script>\n document.getElementById('my-accordion').addEventListener('mdsAccordionChange', (e) => {\n console.log('Selezione corrente:', e.detail.selected);\n });\n</script>\n```\n\n#### Do Not Mix `mds-accordion-item` and `mds-accordion-timer-item`\n\n[`mds-accordion-timer`](../mds-accordion-timer/AGENTS.md) and its child [`mds-accordion-timer-item`](../mds-accordion-timer-item/AGENTS.md) are a separate compound pair. Slotting timer items into a plain accordion (or vice versa) breaks internal event wiring because each parent only listens for its own child's events.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion>\n <mds-accordion-timer-item description=\"Avanzamento automatico\">\n <mds-text>Contenuto con timer.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion>\n\n<!-- CORRECT - use mds-accordion-timer with mds-accordion-timer-item -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Avanzamento automatico\">\n <mds-text>Contenuto con timer.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Do Not Pierce Shadow DOM to Style Internals\n\nThe only supported customization surface is the public `--mds-accordion-*` CSS custom properties and the documented `::part()` names on `mds-accordion-item` (`content`, `icon`, `label`). Targeting undocumented internals via `>>>` or deep class selectors couples code to the Shadow DOM implementation and breaks on minor releases.\n\n```css\n/* INCORRECT */\nmds-accordion >>> .action {\n font-weight: bold;\n}\nmds-accordion-item::part(spinner) {\n display: none;\n}\n\n/* CORRECT */\nmds-accordion {\n --mds-accordion-color: rgb(var(--magma-text-default));\n}\nmds-accordion-item::part(label) {\n font-style: italic;\n}\n```\n"
|
|
29
29
|
},
|
|
30
30
|
"props": [
|
|
@@ -215,8 +215,8 @@
|
|
|
215
215
|
}
|
|
216
216
|
],
|
|
217
217
|
"usage": {
|
|
218
|
-
"1. Description": "The `<mds-accordion-item>` web component is a single collapsible panel of the Magma Design System, designed to be slotted inside its parent [`<mds-accordion>`](../mds-accordion/AGENTS.md). It renders a header button paired with an expandable content region; the parent controls which items are open.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-accordion>`; it is not used standalone, and the parent's slot should hold only `mds-accordion-item` elements, not mixed child types.\n- **Parent-driven selection**: Clicking the header requests a toggle, but the authoritative open/closed state is resolved by the parent - in single mode opening one item closes its siblings, while in `multiple` mode each item toggles independently.\n- **Emitted events**: `mdsAccordionItemSelect` on open, `mdsAccordionItemUnselect` on close, and `mdsAccordionItemChange` on any toggle, each carrying `{ id, selected }`.\n- **Default slot**: Holds the collapsible body content (text, HTML, or components).\n\n#### Properties & Visual Configurations\n\n- **`label`** sets the always-visible header text shown whether the item is open or closed.\n- **`selected`** controls whether the panel is expanded; leave it to the parent to manage in coordinated accordions, or set it initially to have a panel start open.\n- **`typography`** picks the title style applied to the header label, defaulting to `h5`. An item is a part of the page, and the title of a part is styled as `h6` (`titles/part` of the design language): write `typography=\"h6\"` until the default moves with the next major (#1218). `action` gives a compact, control-like header. The
|
|
219
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-accordion-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Accordion\n\nThe canonical form. Place one or more `<mds-accordion-item>` elements as direct children of [`<mds-accordion>`](../mds-accordion/AGENTS.md). Provide `label` for the header text and put the body content in the default slot.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Cos'e' Magma?\">\n <mds-text>Magma e' il design system di Maggioli, basato su web components.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Come si installa?\">\n <mds-text>Importa il loader e chiama defineCustomElements() nell'entry point.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"E' compatibile con React?\">\n <mds-text>Si', usa il pacchetto @maggioli-design-system/magma-react.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Panel Open by Default\n\nSet `selected` on the item you want pre-expanded. The parent does not resolve conflicts on load, so in single mode set it on one item only, unless `multiple` is also set on the parent.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Introduzione\" selected>\n <mds-text>Questa sezione e' aperta per impostazione predefinita.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Prerequisiti\">\n <mds-text>Node.js 18+ e un package manager npm o pnpm.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Multiple Panels Open Simultaneously\n\nAdd `multiple` to `<mds-accordion>` so the user can expand more than one panel at once. Individual items do not change - the parent mode governs the behaviour.\n\n```html\n<mds-accordion multiple>\n <mds-accordion-item label=\"Configurazione di base\">\n <mds-text>Imposta i token di colore e il tema nell'entry point dell'applicazione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Configurazione avanzata\" selected>\n <mds-text>Personalizza i CSS custom properties per adattare il tema al brand.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Integrazione CI/CD\" selected>\n <mds-text>Configura il job di build per generare documentation.json e readme.md.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Non-closable Accordion\n\nSet the parent `disable-close` attribute to prevent the user from collapsing an open panel. An open item then stays open until another item is clicked; with `multiple`, the last open item cannot be closed. Because `disableClose` defaults to `false`, just add the boolean attribute to enable mandatory selection.\n\n```html\n<mds-accordion disable-close>\n <mds-accordion-item label=\"Passo 1 - Installazione\" selected>\n <mds-text>Esegui npm install @maggioli-design-system/magma per aggiungere il pacchetto.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Passo 2 - Configurazione\">\n <mds-text>Importa defineCustomElements e registra i componenti nell'app.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### The Title of an Item Is a Part\n\nAn item is a part of the page, whose title is styled as `h6` (`titles/part`): write `typography=\"h6\"`, until the default moves from `h5` with the next major (#1218).
|
|
218
|
+
"1. Description": "The `<mds-accordion-item>` web component is a single collapsible panel of the Magma Design System, designed to be slotted inside its parent [`<mds-accordion>`](../mds-accordion/AGENTS.md). It renders a header button paired with an expandable content region; the parent controls which items are open.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-accordion>`; it is not used standalone, and the parent's slot should hold only `mds-accordion-item` elements, not mixed child types.\n- **Parent-driven selection**: Clicking the header requests a toggle, but the authoritative open/closed state is resolved by the parent - in single mode opening one item closes its siblings, while in `multiple` mode each item toggles independently.\n- **Emitted events**: `mdsAccordionItemSelect` on open, `mdsAccordionItemUnselect` on close, and `mdsAccordionItemChange` on any toggle, each carrying `{ id, selected }`.\n- **Default slot**: Holds the collapsible body content (text, HTML, or components).\n\n#### Properties & Visual Configurations\n\n- **`label`** sets the always-visible header text shown whether the item is open or closed.\n- **`selected`** controls whether the panel is expanded; leave it to the parent to manage in coordinated accordions, or set it initially to have a panel start open.\n- **`typography`** picks the title style applied to the header label, defaulting to `h5`. An item is a part of the page, and the title of a part is styled as `h6` (`titles/part` of the design language): write `typography=\"h6\"` until the default moves with the next major (#1218). `action` gives a compact, control-like header. The value is a style only: the label is a `<span>` inside the `<button>` that opens the item, whatever its style.\n- **`tag`** puts the title in the outline of the page, at the level of its place: `tag=\"h3\"` under a section titled `h2`. The heading wraps the button, as the Accordion pattern of the WAI-ARIA Authoring Practices does, so whoever navigates by headings reaches each item. Left out, the item is not a heading: the component cannot know its place, and the level of its style (`h6`) would skip the levels in between.\n",
|
|
219
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-accordion-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Accordion\n\nThe canonical form. Place one or more `<mds-accordion-item>` elements as direct children of [`<mds-accordion>`](../mds-accordion/AGENTS.md). Provide `label` for the header text and put the body content in the default slot.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Cos'e' Magma?\">\n <mds-text>Magma e' il design system di Maggioli, basato su web components.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Come si installa?\">\n <mds-text>Importa il loader e chiama defineCustomElements() nell'entry point.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"E' compatibile con React?\">\n <mds-text>Si', usa il pacchetto @maggioli-design-system/magma-react.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Panel Open by Default\n\nSet `selected` on the item you want pre-expanded. The parent does not resolve conflicts on load, so in single mode set it on one item only, unless `multiple` is also set on the parent.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Introduzione\" selected>\n <mds-text>Questa sezione e' aperta per impostazione predefinita.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Prerequisiti\">\n <mds-text>Node.js 18+ e un package manager npm o pnpm.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Multiple Panels Open Simultaneously\n\nAdd `multiple` to `<mds-accordion>` so the user can expand more than one panel at once. Individual items do not change - the parent mode governs the behaviour.\n\n```html\n<mds-accordion multiple>\n <mds-accordion-item label=\"Configurazione di base\">\n <mds-text>Imposta i token di colore e il tema nell'entry point dell'applicazione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Configurazione avanzata\" selected>\n <mds-text>Personalizza i CSS custom properties per adattare il tema al brand.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Integrazione CI/CD\" selected>\n <mds-text>Configura il job di build per generare documentation.json e readme.md.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Non-closable Accordion\n\nSet the parent `disable-close` attribute to prevent the user from collapsing an open panel. An open item then stays open until another item is clicked; with `multiple`, the last open item cannot be closed. Because `disableClose` defaults to `false`, just add the boolean attribute to enable mandatory selection.\n\n```html\n<mds-accordion disable-close>\n <mds-accordion-item label=\"Passo 1 - Installazione\" selected>\n <mds-text>Esegui npm install @maggioli-design-system/magma per aggiungere il pacchetto.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Passo 2 - Configurazione\">\n <mds-text>Importa defineCustomElements e registra i componenti nell'app.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### The Title of an Item Is a Part\n\nAn item is a part of the page, whose title is styled as `h6` (`titles/part`): write `typography=\"h6\"`, until the default moves from `h5` with the next major (#1218). `typography` is the style only; `tag` gives the level of the title in the outline, one below the title of the section that holds the accordion (`h3` under an `h2`). Use `action` for a compact, control-like header.\n\n```html\n<mds-text typography=\"section\" tag=\"h2\">Domande frequenti</mds-text>\n<mds-accordion>\n <mds-accordion-item label=\"Come gestisco gli aggiornamenti?\" typography=\"h6\" tag=\"h3\">\n <mds-text>Ogni release e' documentata nel changelog con note di migrazione.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Posso personalizzare i colori?\" typography=\"h6\" tag=\"h3\">\n <mds-text>Si', tramite i CSS custom properties esposti da ogni componente.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\nThe heading wraps the button that opens the item, as the Accordion pattern of the WAI-ARIA Authoring Practices does: a screen reader lists the questions among the headings of the page, under Domande frequenti. Left out, `tag` leaves the item a button only, out of the outline; never write the level of the style (`tag=\"h6\"` under an `h2`), which skips the levels in between.\n\n#### Rich Slot Content\n\nThe default slot accepts any HTML or components - not just text. Use it for structured content such as lists, forms, or nested components.\n\n```html\n<mds-accordion>\n <mds-accordion-item label=\"Dettagli del progetto\">\n <mds-text typography=\"h6\">Tecnologie utilizzate</mds-text>\n <mds-list>\n <mds-list-item>StencilJS</mds-list-item>\n <mds-list-item>TypeScript</mds-list-item>\n <mds-list-item>Storybook</mds-list-item>\n </mds-list>\n </mds-accordion-item>\n <mds-accordion-item label=\"Contatti del team\">\n <mds-text>Scrivi a design-system@maggioli.it per supporto tecnico.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Listening to Item Events\n\n`mdsAccordionItemChange` fires on every toggle; `mdsAccordionItemSelect` fires only on open; `mdsAccordionItemUnselect` fires only on close. Use `mdsAccordionItemChange` when you only need to react to any state change, or the specific event when you need to handle open and close differently. The parent overwrites each item's `id` with `item-<index>` on load, and that is the `detail.id`: do not select items by an `id` of your own.\n\n```html\n<mds-accordion id=\"faq\">\n <mds-accordion-item label=\"Domanda frequente 1\">\n <mds-text>Risposta alla prima domanda.</mds-text>\n </mds-accordion-item>\n <mds-accordion-item label=\"Domanda frequente 2\">\n <mds-text>Risposta alla seconda domanda.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n\n<script>\n document.querySelector('#faq').addEventListener('mdsAccordionItemChange', (e) => {\n console.log('item changed:', e.detail.id, 'selected:', e.detail.selected);\n });\n\n document.querySelector('#faq mds-accordion-item').addEventListener('mdsAccordionItemSelect', (e) => {\n console.log('faq-1 opened');\n });\n</script>\n```\n\n#### Styling Customization\n\nStyle each item only through its public `--mds-accordion-item-*` CSS custom properties. Setting the public `--mds-accordion-*` properties on the parent `<mds-accordion>` propagates to all children via the cascade variables the items consume.\n\n```css\n/* Customize all items via the parent */\nmds-accordion {\n --mds-accordion-padding-selected: calc(var(--spacing) * 600) 0 calc(var(--spacing) * 800) 0;\n --mds-accordion-padding-unselected: calc(var(--spacing) * 400) 0;\n}\n\n/* Or target a single item directly */\n.sidebar mds-accordion-item {\n --mds-accordion-item-color: rgb(var(--magma-text-default));\n}\n```\n",
|
|
220
220
|
"3. Mistakes": "Common incorrect uses of `<mds-accordion-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `mds-accordion-item` Outside `mds-accordion`\n\nThe item relies on the parent to give it an `id` when it has none, manage sibling state, and emit coordinated change events. Placed standalone it still toggles, but nothing coordinates it, no `mdsAccordionChange` is emitted, and its events carry an empty `id`.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion-item label=\"Sezione autonoma\">\n <mds-text>Contenuto senza accordeon genitore.</mds-text>\n</mds-accordion-item>\n\n<!-- CORRECT -->\n<mds-accordion>\n <mds-accordion-item label=\"Sezione autonoma\">\n <mds-text>Contenuto all'interno del genitore corretto.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Wrap `mds-accordion-item` in Extra Elements\n\nItems are direct children of `mds-accordion` by contract (see [`agents/conventions.md`](../../../../agents/conventions.md)). The parent still finds wrapped items, since it queries every descendant, but the borders of an open item depend on its position among its siblings (`:first-child` / `:last-child`), which a wrapper changes.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion>\n <div class=\"group\">\n <mds-accordion-item label=\"FAQ 1\">\n <mds-text>Risposta alla prima domanda.</mds-text>\n </mds-accordion-item>\n </div>\n</mds-accordion>\n\n<!-- CORRECT -->\n<mds-accordion>\n <mds-accordion-item label=\"FAQ 1\">\n <mds-text>Risposta alla prima domanda.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Set `label` via the Default Slot\n\n`label` is a required prop that renders the header button text, which is also the button's accessible name; the default slot holds only the collapsible body content. Putting header text in the slot places it inside the body region and leaves the required `label` prop empty, breaking both layout and accessibility.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion>\n <mds-accordion-item>\n Dettagli dell'ordine\n </mds-accordion-item>\n</mds-accordion>\n\n<!-- CORRECT -->\n<mds-accordion>\n <mds-accordion-item label=\"Dettagli dell'ordine\">\n <mds-text>Numero ordine: 12345, data: 01/06/2026.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Override Open/Close State by Piercing the Shadow DOM\n\n`selected` is reflected as a host attribute and is writable via JavaScript. Targeting the internal `.content` div or `.icon` element via `>>>` or undocumented class names to show/hide content manually bypasses the coordinated state machine and breaks sibling sync. The documented `content` part styles the panel body; it does not open it. Setting `selected` from JavaScript emits no event and does not close the siblings: in single mode, unset the open item yourself.\n\n```css\n/* INCORRECT */\nmds-accordion-item >>> .content {\n grid-template-rows: 1fr;\n}\n```\n\n```js\n/* CORRECT - toggle via the reflected property */\nconst item = document.querySelector('mds-accordion-item#shipping'); // the id you gave the item\nitem.selected = true;\n```\n\n#### Do Not Listen for Native `click` or `change` Events Instead of the Documented `mds*` Events\n\nA native `click` bubbles up from anywhere inside the item, body content included, and carries no state; there is no native `change` event on this component. The documented events `mdsAccordionItemChange`, `mdsAccordionItemSelect`, and `mdsAccordionItemUnselect` are the designed surface.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion id=\"faq\">\n <mds-accordion-item label=\"Domanda 1\">\n <mds-text>Risposta 1.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n\n<script>\n document.querySelector('#faq mds-accordion-item').addEventListener('click', () => {\n console.log('clicked - also fires for clicks inside the body');\n });\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('#faq mds-accordion-item').addEventListener('mdsAccordionItemChange', (e) => {\n console.log('stato:', e.detail.selected);\n });\n</script>\n```\n\n#### Do Not Use `<details>`/`<summary>` Inside the Slot as a Second Disclosure Layer\n\nThe item already is a styled disclosure widget. Nesting a native `<details>` inside the slot creates redundant expand/collapse semantics, duplicates keyboard interactions, and produces conflicting visual states.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion>\n <mds-accordion-item label=\"Configurazione\">\n <details>\n <summary>Mostra dettagli</summary>\n <p>Parametri avanzati di configurazione.</p>\n </details>\n </mds-accordion-item>\n</mds-accordion>\n\n<!-- CORRECT - put content directly in the slot -->\n<mds-accordion>\n <mds-accordion-item label=\"Configurazione\">\n <mds-text typography=\"h6\">Parametri avanzati</mds-text>\n <mds-text>Descrizione dei parametri di configurazione avanzata.</mds-text>\n </mds-accordion-item>\n</mds-accordion>\n```\n"
|
|
221
221
|
},
|
|
222
222
|
"props": [
|
|
@@ -269,6 +269,60 @@
|
|
|
269
269
|
"getter": false,
|
|
270
270
|
"setter": false
|
|
271
271
|
},
|
|
272
|
+
{
|
|
273
|
+
"name": "tag",
|
|
274
|
+
"type": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | undefined",
|
|
275
|
+
"complexType": {
|
|
276
|
+
"original": "TypographyHeadingTagType",
|
|
277
|
+
"resolved": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | undefined",
|
|
278
|
+
"references": {
|
|
279
|
+
"TypographyHeadingTagType": {
|
|
280
|
+
"location": "import",
|
|
281
|
+
"path": "@type/text",
|
|
282
|
+
"id": "src/type/text.ts::TypographyHeadingTagType",
|
|
283
|
+
"referenceLocation": "TypographyHeadingTagType"
|
|
284
|
+
}
|
|
285
|
+
}
|
|
286
|
+
},
|
|
287
|
+
"mutable": false,
|
|
288
|
+
"attr": "tag",
|
|
289
|
+
"reflectToAttr": false,
|
|
290
|
+
"docs": "Specifies the heading level of the title, the level of its place in the outline of the\npage (`h3` under a section titled `h2`): the heading wraps the button that opens the item,\nas the Accordion pattern of the WAI-ARIA Authoring Practices does. Left out, the item is\nnot a heading: only the page knows its place, and the level of the style would skip the\nlevels in between",
|
|
291
|
+
"docsTags": [],
|
|
292
|
+
"values": [
|
|
293
|
+
{
|
|
294
|
+
"value": "h1",
|
|
295
|
+
"type": "string"
|
|
296
|
+
},
|
|
297
|
+
{
|
|
298
|
+
"value": "h2",
|
|
299
|
+
"type": "string"
|
|
300
|
+
},
|
|
301
|
+
{
|
|
302
|
+
"value": "h3",
|
|
303
|
+
"type": "string"
|
|
304
|
+
},
|
|
305
|
+
{
|
|
306
|
+
"value": "h4",
|
|
307
|
+
"type": "string"
|
|
308
|
+
},
|
|
309
|
+
{
|
|
310
|
+
"value": "h5",
|
|
311
|
+
"type": "string"
|
|
312
|
+
},
|
|
313
|
+
{
|
|
314
|
+
"value": "h6",
|
|
315
|
+
"type": "string"
|
|
316
|
+
},
|
|
317
|
+
{
|
|
318
|
+
"type": "undefined"
|
|
319
|
+
}
|
|
320
|
+
],
|
|
321
|
+
"optional": true,
|
|
322
|
+
"required": false,
|
|
323
|
+
"getter": false,
|
|
324
|
+
"setter": false
|
|
325
|
+
},
|
|
272
326
|
{
|
|
273
327
|
"name": "typography",
|
|
274
328
|
"type": "\"action\" | \"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | undefined",
|
|
@@ -287,7 +341,7 @@
|
|
|
287
341
|
"mutable": false,
|
|
288
342
|
"attr": "typography",
|
|
289
343
|
"reflectToAttr": false,
|
|
290
|
-
"docs": "Specifies the typography of the title. An item is a part of the page, whose title is\nstyled as `h6` (`titles/part`, #1189): write `h6` until the default moves with the next\nmajor (#1218).
|
|
344
|
+
"docs": "Specifies the typography of the title. An item is a part of the page, whose title is\nstyled as `h6` (`titles/part`, #1189): write `h6` until the default moves with the next\nmajor (#1218). It is the style only: the level of the title in the outline is `tag`",
|
|
291
345
|
"docsTags": [
|
|
292
346
|
{
|
|
293
347
|
"name": "default",
|
|
@@ -679,8 +733,8 @@
|
|
|
679
733
|
}
|
|
680
734
|
],
|
|
681
735
|
"usage": {
|
|
682
|
-
"1. Description": "The `<mds-accordion-timer-item>` web component is the single collapsible panel of a timed, auto-advancing accordion, designed to live exclusively inside its parent [`<mds-accordion-timer>`](../mds-accordion-timer/AGENTS.md). It renders a header button paired with a progress bar and a region that reveals the slotted content while the item is selected.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-accordion-timer>`, alongside other `<mds-accordion-timer-item>` siblings. It is not used standalone or mixed with other child types, since the parent drives the rotating timer across the items.\n- **Selection is parent-orchestrated**: `selected` represents the open state, but only one sibling is open at a time - the parent advances selection on the timer or on a user click.\n- **Click reports up**: Clicking the header of a closed item emits `mdsAccordionTimerItemClickSelect`, and the parent opens it, pauses and re-anchors its timer on it. Clicking the open item does nothing: it stays open.\n- **Programmatic selection**: Setting `selected` to `true` emits `mdsAccordionTimerItemSelect`, and the parent restarts the countdown from the beginning of that item. A click reaches `selected` through the parent, so it emits this event as well, which the parent does not take as a second selection.\n- **Hover pauses the countdown**: While selected, pointer enter/leave emit `mdsAccordionTimerItemMouseEnterSelect` / `mdsAccordionTimerItemMouseLeaveSelect`, which the parent uses to pause and resume the timer. These fire only when the item is currently selected.\n\n#### Properties & Visual Configurations\n\n- **`description`** (required): the title text shown on the header in both open and closed states; it also supplies the accessible label of the content region.\n- **`typography`**: picks the title style of the header text, defaulting to `h5`. An item is a part of the page, styled as `h6` (`titles/part` of the design language): write `typography=\"h6\"` until the default moves with the next major (#1218). The header
|
|
683
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-accordion-timer-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Timed Accordion\n\nThe canonical form. Always place `<mds-accordion-timer-item>` as a direct child of [`<mds-accordion-timer>`](../mds-accordion-timer/AGENTS.md). Provide a `description` for each item - it becomes the header label and the accessible name for the content region. Mark one item `selected`: without it the timer does not start.\n\n```html\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Introduzione al progetto\" selected>\n <mds-text>Contenuto dell'introduzione al progetto.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Obiettivi principali\">\n <mds-text>Elenco degli obiettivi principali del progetto.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Conclusioni\">\n <mds-text>Riepilogo e prossimi passi.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Setting the Initially Open Item\n\nMark one item `selected` to define which panel is open on load. The parent reads this state at `componentDidLoad` to anchor its timer on that item. Mark at most one item; the parent will enforce exclusive selection after load.\n\n```html\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Fase uno\" selected>\n <mds-text>Descrizione della fase uno.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Fase due\">\n <mds-text>Descrizione della fase due.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Per-Item Duration Override\n\nSet `duration` (in milliseconds) on a single item to give it a different display time than the global `duration` set on the parent. Omit `duration` on items that should use the parent's default.\n\n```html\n<mds-accordion-timer duration=\"5000\">\n <mds-accordion-timer-item description=\"Panoramica rapida\" duration=\"2000\" selected>\n <mds-text>Questa sezione scorre piu velocemente delle altre.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Dettagli tecnici\" duration=\"12000\">\n <mds-text>Questa sezione richiede piu tempo per la lettura.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Contatti\">\n <mds-text>Usa la durata globale di 5000 ms.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### The Title of an Item Is a Part\n\nAn item is a part of the page, whose title is styled as `h6` (`titles/part`): write `typography=\"h6\"`, until the default moves from `h5` with the next major (#1218).
|
|
736
|
+
"1. Description": "The `<mds-accordion-timer-item>` web component is the single collapsible panel of a timed, auto-advancing accordion, designed to live exclusively inside its parent [`<mds-accordion-timer>`](../mds-accordion-timer/AGENTS.md). It renders a header button paired with a progress bar and a region that reveals the slotted content while the item is selected.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-accordion-timer>`, alongside other `<mds-accordion-timer-item>` siblings. It is not used standalone or mixed with other child types, since the parent drives the rotating timer across the items.\n- **Selection is parent-orchestrated**: `selected` represents the open state, but only one sibling is open at a time - the parent advances selection on the timer or on a user click.\n- **Click reports up**: Clicking the header of a closed item emits `mdsAccordionTimerItemClickSelect`, and the parent opens it, pauses and re-anchors its timer on it. Clicking the open item does nothing: it stays open.\n- **Programmatic selection**: Setting `selected` to `true` emits `mdsAccordionTimerItemSelect`, and the parent restarts the countdown from the beginning of that item. A click reaches `selected` through the parent, so it emits this event as well, which the parent does not take as a second selection.\n- **Hover pauses the countdown**: While selected, pointer enter/leave emit `mdsAccordionTimerItemMouseEnterSelect` / `mdsAccordionTimerItemMouseLeaveSelect`, which the parent uses to pause and resume the timer. These fire only when the item is currently selected.\n\n#### Properties & Visual Configurations\n\n- **`description`** (required): the title text shown on the header in both open and closed states; it also supplies the accessible label of the content region.\n- **`typography`**: picks the title style of the header text, defaulting to `h5`. An item is a part of the page, styled as `h6` (`titles/part` of the design language): write `typography=\"h6\"` until the default moves with the next major (#1218). The value is a style only: the header is a `<span>` inside the `<button>` that opens the item, whatever its style.\n- **`tag`**: puts the title in the outline of the page, at the level of its place: `tag=\"h3\"` under a section titled `h2`. The heading wraps the button, as the Accordion pattern of the WAI-ARIA Authoring Practices does. Left out, the item is not a heading: the component cannot know its place, and the level of its style (`h6`) would skip the levels in between.\n- **`selected`**: marks this item as the open one. You normally set it on a single item to define the initial open panel; thereafter the parent owns it.\n- **`duration`**: an optional per-item override (in ms) for how long this item stays open before the parent auto-advances, overriding the parent's global `duration` for this item only.\n- **`progress`** and **`uuid`** are managed by the parent at runtime; do not set them manually.\n",
|
|
737
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-accordion-timer-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Timed Accordion\n\nThe canonical form. Always place `<mds-accordion-timer-item>` as a direct child of [`<mds-accordion-timer>`](../mds-accordion-timer/AGENTS.md). Provide a `description` for each item - it becomes the header label and the accessible name for the content region. Mark one item `selected`: without it the timer does not start.\n\n```html\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Introduzione al progetto\" selected>\n <mds-text>Contenuto dell'introduzione al progetto.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Obiettivi principali\">\n <mds-text>Elenco degli obiettivi principali del progetto.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Conclusioni\">\n <mds-text>Riepilogo e prossimi passi.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Setting the Initially Open Item\n\nMark one item `selected` to define which panel is open on load. The parent reads this state at `componentDidLoad` to anchor its timer on that item. Mark at most one item; the parent will enforce exclusive selection after load.\n\n```html\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Fase uno\" selected>\n <mds-text>Descrizione della fase uno.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Fase due\">\n <mds-text>Descrizione della fase due.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Per-Item Duration Override\n\nSet `duration` (in milliseconds) on a single item to give it a different display time than the global `duration` set on the parent. Omit `duration` on items that should use the parent's default.\n\n```html\n<mds-accordion-timer duration=\"5000\">\n <mds-accordion-timer-item description=\"Panoramica rapida\" duration=\"2000\" selected>\n <mds-text>Questa sezione scorre piu velocemente delle altre.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Dettagli tecnici\" duration=\"12000\">\n <mds-text>Questa sezione richiede piu tempo per la lettura.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Contatti\">\n <mds-text>Usa la durata globale di 5000 ms.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### The Title of an Item Is a Part\n\nAn item is a part of the page, whose title is styled as `h6` (`titles/part`): write `typography=\"h6\"`, until the default moves from `h5` with the next major (#1218). `typography` is the style only; `tag` gives the level of the title in the outline, one below the title of the section that holds the accordion (`h3` under an `h2`).\n\n```html\n<mds-text typography=\"section\" tag=\"h2\">Come funziona</mds-text>\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Argomento principale\" typography=\"h6\" tag=\"h3\">\n <mds-text>Contenuto dell'argomento principale.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Sotto-argomento\" typography=\"h6\" tag=\"h3\">\n <mds-text>Approfondimento del sotto-argomento.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\nThe heading wraps the button that opens the item, as the Accordion pattern of the WAI-ARIA Authoring Practices does. Left out, `tag` leaves the item a button only, out of the outline; never write the level of the style (`tag=\"h6\"` under an `h2`), which skips the levels in between.\n\n#### Rich Slotted Content\n\nThe default slot accepts HTML elements and components, not only plain text. Use it to compose images, lists, or nested components inside the disclosure panel.\n\n```html\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Caratteristiche del prodotto\">\n <mds-img src=\"/images/prodotto.jpg\" alt=\"Foto del prodotto\"></mds-img>\n <mds-text>\n Il prodotto include le seguenti funzionalita: gestione utenti, reportistica avanzata e\n integrazione con i sistemi esistenti.\n </mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Prezzi e licenze\">\n <mds-text>Contatta il nostro team commerciale per un preventivo personalizzato.</mds-text>\n <mds-button label=\"Richiedi preventivo\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Reacting to Item Changes\n\nListen for `mdsAccordionTimerItemClickSelect` to detect user-initiated selection (it fires only when a click opens the item). `mdsAccordionTimerItemSelect` on the item fires on every selection - click, code or timer - and `mdsAccordionTimerChange` on the parent reports the new index.\n\n```html\n<mds-accordion-timer id=\"timer\">\n <mds-accordion-timer-item description=\"Notizie in evidenza\" id=\"item-0\" selected>\n <mds-text>Prima notizia in evidenza della giornata.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Aggiornamenti recenti\" id=\"item-1\">\n <mds-text>Ultimi aggiornamenti disponibili.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n\n<script>\n document.getElementById('item-0').addEventListener('mdsAccordionTimerItemClickSelect', (e) => {\n console.log('selezione manuale', e.detail);\n });\n\n document.getElementById('timer').addEventListener('mdsAccordionTimerChange', (e) => {\n console.log('avanzamento automatico, indice:', e.detail.index);\n });\n</script>\n```\n\n#### Styling Customization\n\nStyle the item only through its public `--mds-accordion-timer-item-*` CSS custom properties. Use semantic color roles wrapped in `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working. Note that `--mds-accordion-timer-item-color` is also inherited from the parent's `--mds-accordion-timer-color` counterpart - setting it on the parent applies to all items at once.\n\n```css\n/* Customise a single item by targeting its host */\n.featured-section mds-accordion-timer-item {\n --mds-accordion-timer-item-color: rgb(var(--magma-accent-fg));\n}\n```\n",
|
|
684
738
|
"3. Mistakes": "Common incorrect uses of `<mds-accordion-timer-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use the Item Outside Its Parent\n\n`<mds-accordion-timer-item>` is a compound child and relies on [`<mds-accordion-timer>`](../mds-accordion-timer/AGENTS.md) to assign `uuid`, write `progress`, and drive selection. Standalone use produces a static, non-advancing disclosure with no progress bar updates.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion-timer-item description=\"Dettagli\">\n <mds-text>Contenuto.</mds-text>\n</mds-accordion-timer-item>\n\n<!-- CORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Dettagli\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Do Not Mix with `mds-accordion-item`\n\n`<mds-accordion-timer-item>` and [`<mds-accordion-item>`](../mds-accordion-item/AGENTS.md) are siblings in different compound families and must not be placed in the same parent. The timer accordion indexes only `mds-accordion-timer-item` children; a mixed-in `mds-accordion-item` is left out of the rotation and toggles on its own.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion-timer>\n <mds-accordion-item label=\"Primo\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-item>\n <mds-accordion-timer-item description=\"Secondo\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n\n<!-- CORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Primo\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Secondo\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Do Not Set `progress` or `uuid` Manually\n\nBoth props are reserved for the parent's runtime orchestration. Setting them by hand breaks the timer's internal state tracking and produces incorrect progress bar rendering.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Primo\" uuid=\"0\" progress=\"50\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n\n<!-- CORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Primo\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Do Not Mark More Than One Item `selected`\n\nThe parent does not enforce single selection at load: every item marked `selected` renders open, and the last one drives the timer until the first change closes the others.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Primo\" selected>\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Secondo\" selected>\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n\n<!-- CORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Primo\" selected>\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n <mds-accordion-timer-item description=\"Secondo\">\n <mds-text>Contenuto.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Do Not Pierce Shadow Parts for Styling\n\nThe documented customization surface is the public `--mds-accordion-timer-item-*` CSS custom properties plus the four shadow parts (`content`, `icon`, `label`, `progress`). Targeting undocumented internals couples code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-accordion-timer-item >>> .action {\n font-weight: bold;\n}\nmds-accordion-timer-item::part(spinner) {\n color: red;\n}\n\n/* CORRECT */\nmds-accordion-timer-item {\n --mds-accordion-timer-item-color: rgb(var(--magma-accent-fg));\n}\nmds-accordion-timer-item::part(label) {\n font-weight: 600;\n}\n```\n\n#### Do Not Omit `description`\n\n`description` is a required prop. It is the only text source for the header label and the accessible name of the content region. Omitting it leaves the button unlabelled and fails accessibility audits.\n\n```html\n<!-- INCORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item>\n <mds-text>Contenuto senza titolo.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n\n<!-- CORRECT -->\n<mds-accordion-timer>\n <mds-accordion-timer-item description=\"Titolo della sezione\">\n <mds-text>Contenuto della sezione.</mds-text>\n </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n"
|
|
685
739
|
},
|
|
686
740
|
"props": [
|
|
@@ -791,6 +845,60 @@
|
|
|
791
845
|
"getter": false,
|
|
792
846
|
"setter": false
|
|
793
847
|
},
|
|
848
|
+
{
|
|
849
|
+
"name": "tag",
|
|
850
|
+
"type": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | undefined",
|
|
851
|
+
"complexType": {
|
|
852
|
+
"original": "TypographyHeadingTagType",
|
|
853
|
+
"resolved": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | undefined",
|
|
854
|
+
"references": {
|
|
855
|
+
"TypographyHeadingTagType": {
|
|
856
|
+
"location": "import",
|
|
857
|
+
"path": "@type/text",
|
|
858
|
+
"id": "src/type/text.ts::TypographyHeadingTagType",
|
|
859
|
+
"referenceLocation": "TypographyHeadingTagType"
|
|
860
|
+
}
|
|
861
|
+
}
|
|
862
|
+
},
|
|
863
|
+
"mutable": false,
|
|
864
|
+
"attr": "tag",
|
|
865
|
+
"reflectToAttr": false,
|
|
866
|
+
"docs": "Specifies the heading level of the title, the level of its place in the outline of the\npage (`h3` under a section titled `h2`): the heading wraps the button that opens the item,\nas the Accordion pattern of the WAI-ARIA Authoring Practices does. Left out, the item is\nnot a heading: only the page knows its place, and the level of the style would skip the\nlevels in between",
|
|
867
|
+
"docsTags": [],
|
|
868
|
+
"values": [
|
|
869
|
+
{
|
|
870
|
+
"value": "h1",
|
|
871
|
+
"type": "string"
|
|
872
|
+
},
|
|
873
|
+
{
|
|
874
|
+
"value": "h2",
|
|
875
|
+
"type": "string"
|
|
876
|
+
},
|
|
877
|
+
{
|
|
878
|
+
"value": "h3",
|
|
879
|
+
"type": "string"
|
|
880
|
+
},
|
|
881
|
+
{
|
|
882
|
+
"value": "h4",
|
|
883
|
+
"type": "string"
|
|
884
|
+
},
|
|
885
|
+
{
|
|
886
|
+
"value": "h5",
|
|
887
|
+
"type": "string"
|
|
888
|
+
},
|
|
889
|
+
{
|
|
890
|
+
"value": "h6",
|
|
891
|
+
"type": "string"
|
|
892
|
+
},
|
|
893
|
+
{
|
|
894
|
+
"type": "undefined"
|
|
895
|
+
}
|
|
896
|
+
],
|
|
897
|
+
"optional": true,
|
|
898
|
+
"required": false,
|
|
899
|
+
"getter": false,
|
|
900
|
+
"setter": false
|
|
901
|
+
},
|
|
794
902
|
{
|
|
795
903
|
"name": "typography",
|
|
796
904
|
"type": "\"action\" | \"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\"",
|
|
@@ -809,7 +917,7 @@
|
|
|
809
917
|
"mutable": false,
|
|
810
918
|
"attr": "typography",
|
|
811
919
|
"reflectToAttr": false,
|
|
812
|
-
"docs": "Specifies the typography of the title. An item is a part of the page, whose title is\nstyled as `h6` (`titles/part`, #1189): write `h6` until the default moves with the next\nmajor (#1218).
|
|
920
|
+
"docs": "Specifies the typography of the title. An item is a part of the page, whose title is\nstyled as `h6` (`titles/part`, #1189): write `h6` until the default moves with the next\nmajor (#1218). It is the style only: the level of the title in the outline is `tag`",
|
|
813
921
|
"docsTags": [
|
|
814
922
|
{
|
|
815
923
|
"name": "default",
|
|
@@ -1029,13 +1137,13 @@
|
|
|
1029
1137
|
"states": [],
|
|
1030
1138
|
"dependents": [],
|
|
1031
1139
|
"dependencies": [
|
|
1032
|
-
"mds-
|
|
1033
|
-
"mds-
|
|
1140
|
+
"mds-text",
|
|
1141
|
+
"mds-progress"
|
|
1034
1142
|
],
|
|
1035
1143
|
"dependencyGraph": {
|
|
1036
1144
|
"mds-accordion-timer-item": [
|
|
1037
|
-
"mds-
|
|
1038
|
-
"mds-
|
|
1145
|
+
"mds-text",
|
|
1146
|
+
"mds-progress"
|
|
1039
1147
|
],
|
|
1040
1148
|
"mds-progress": [
|
|
1041
1149
|
"mds-radial-progress"
|
|
@@ -2322,9 +2430,9 @@
|
|
|
2322
2430
|
}
|
|
2323
2431
|
],
|
|
2324
2432
|
"usage": {
|
|
2325
|
-
"1. Description": "The `<mds-banner>` web component is the Magma Design System surface for contextual, in-page messages - informational notices, status callouts, and alerts - pairing an optional icon, headline, body text, and inline actions inside a single themed box.\n\n#### Semantic Behavior\n\n- **Variant-driven ARIA**: The announcement role is derived from `variant`, not set manually. `error` and `warning` announce assertively (`role=\"alert\"`); `ai`, `info`, `primary`, and `success` announce politely (`role=\"status\"`); `light` and `dark` are decorative and silent.\n- **Headline as label**: When `headline` is set it also becomes the banner's accessible label.\n- **Dismissal**: When `dismissible` is true a close button is rendered; activating it emits `mdsBannerClose` and, if the banner sits inside an `mds-modal`, closes that modal.\n- **Localized close button**: The close button title is localized (el/en/es/it) from the host language.\n- **Action slot**: The `action` region is rendered only when a direct `[slot=\"action\"]` child is present, so banners without actions produce no empty container.\n\n- **The row of actions stacks when the banner is narrow**: under `--magma-container-actions` of its content (380px) every action of the `action` slot takes the full width, in the order of the row, the main action at the bottom (`actions/stacked`).\n- **Fields take the step below**: a neutral banner paints `surface-overlay`, so a field inside it paints `surface-default` (`--magma-field-fill`); a banner of a status with `tone=\"strong\"` paints a tint, and its fields keep `overlay`.\n\n#### Properties & Visual Configurations\n\nThis component uses the shared `variant` / `tone` ladders defined in [`agents/variants.md`](../../../../agents/variants.md); pick the `variant` according to the message's semantic weight, since it also governs the ARIA behavior described above. `tone` is limited to the minimal-box set (`'weak'`, `'strong'`, `'box'`), defaulting to `'weak'`.\n\n#### Other behavioral props\n\n- **`hideCockade`** (default `false`) removes the colored decorative badge wrapping the leading `icon`; set it for a flatter icon presentation.\n- **`icon`** is a Magma icon library slug shown at the top-left, surfaced as decorative.\n- **`dismissible`** shows the close button - choose it for transient or user-acknowledged messages rather than persistent context.\n- **`deletable`** is the old name of `dismissible`, deprecated: the button dismisses the message, it deletes nothing. It still works, and goes in the next major.\n- The **default slot** carries the body text/markup; the **`action` slot** holds inline controls, with `mds-button` the recommended element.\n",
|
|
2326
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-banner>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Informational Banner\n\nThe baseline usage. Provide `variant=\"info\"` and place the body copy in the default slot. The component derives `role=\"status\"` and `aria-live=\"polite\"` automatically from the variant.\n\n```html\n<mds-banner variant=\"info\">\n <mds-text typography=\"detail\">\n Il sistema e in manutenzione programmata dalle 22:00 alle 23:00.\n </mds-text>\n</mds-banner>\n```\n\n#### Status Variants\n\nPick the variant that matches the message's semantic weight. `error` and `warning` set `role=\"alert\"` with assertive live region; the others use `role=\"status\"` with polite announcement.\n\n```html\n<!-- Esito positivo -->\n<mds-banner variant=\"success\">\n <mds-text typography=\"detail\">Dati salvati correttamente.</mds-text>\n</mds-banner>\n\n<!-- Avviso non bloccante -->\n<mds-banner variant=\"warning\">\n <mds-text typography=\"detail\">La sessione scadra tra 5 minuti.</mds-text>\n</mds-banner>\n\n<!-- Errore bloccante -->\n<mds-banner variant=\"error\">\n <mds-text typography=\"detail\">Impossibile completare l'operazione. Riprovare.</mds-text>\n</mds-banner>\n```\n\n#### Banner with Headline\n\nUse the `headline` prop to add a title above the body text. The headline is also used as the banner's accessible label (`aria-label`).\n\n```html\n<mds-banner variant=\"warning\" headline=\"Licenza in scadenza\">\n <mds-text typography=\"detail\">\n La licenza del servizio scadra tra 7 giorni. Rinnova ora per non interrompere il servizio.\n </mds-text>\n</mds-banner>\n```\n\n#### Banner with Icon\n\nSet `icon` to a Magma icon slug. The icon is decorative (`aria-hidden=\"true\"`). The colored badge wrapping the icon is shown by default; add `hide-cockade` for a flatter look.\n\n```html\n<!-- Con cockade (default) -->\n<mds-banner variant=\"info\" icon=\"mi/baseline/info\" headline=\"Aggiornamento disponibile\">\n <mds-text typography=\"detail\">E disponibile una nuova versione dell'applicazione.</mds-text>\n</mds-banner>\n\n<!-- Senza cockade -->\n<mds-banner variant=\"success\" icon=\"mi/baseline/check-circle\" hide-cockade>\n <mds-text typography=\"detail\">Operazione completata.</mds-text>\n</mds-banner>\n```\n\n#### Dismissible Banner\n\nSet `dismissible` to show a close button. The button emits `mdsBannerClose` when activated. Listen for the event to remove the banner from the DOM or update application state.\n\n```html\n<mds-banner variant=\"info\" dismissible id=\"promo-banner\">\n <mds-text typography=\"detail\">\n Scopri le nuove funzioni premium disponibili nel tuo piano.\n </mds-text>\n</mds-banner>\n\n<script>\n document.querySelector('#promo-banner').addEventListener('mdsBannerClose', () => {\n document.querySelector('#promo-banner').remove();\n });\n</script>\n```\n\n#### Banner with Action Buttons\n\nSlot `<mds-button>` elements with `slot=\"action\"` to add inline controls. The action region is shown only while at least one `[slot=\"action\"]` child is present, and it follows the actions added or removed after the first render. Match the button variant to the banner variant for visual consistency.\n\n```html\n<mds-banner variant=\"warning\" headline=\"Abbonamento scaduto\">\n <mds-text typography=\"detail\">\n La licenza di questo servizio e scaduta. Il servizio continua a funzionare\n ma non puoi utilizzare le funzioni premium.\n </mds-text>\n <mds-button slot=\"action\" variant=\"warning\" tone=\"outline\">Annulla</mds-button>\n <mds-button slot=\"action\" variant=\"warning\" tone=\"strong\">Rinnova abbonamento</mds-button>\n</mds-banner>\n```\n\n#### Tone for Visual Emphasis\n\n`tone` controls emphasis without changing the semantic variant. `strong` paints the status tint on the whole banner, `weak` (default) keeps a neutral raised surface and colours only the icon, and `box` adds a solid box shadow for high-contrast placements. `mds-banner` accepts only `weak`, `strong`, and `box` - not `outline` or `text`.\n\n```html\n<!-- Bassa enfasi (default) -->\n<mds-banner variant=\"error\" tone=\"weak\">\n <mds-text typography=\"detail\">Errore di validazione nei campi del modulo.</mds-text>\n</mds-banner>\n\n<!-- Alta enfasi -->\n<mds-banner variant=\"error\" tone=\"strong\">\n <mds-text typography=\"detail\">Account bloccato per attivita sospetta. Contatta il supporto.</mds-text>\n</mds-banner>\n```\n\n#### Dark and Light Decorative Variants\n\n`variant=\"dark\"` and `variant=\"light\"` are neutral, decorative banners without an ARIA live region (`role=\"presentation\"`). Use them for non-critical UI chrome - announcements or promotional content that does not require immediate attention.\n\n```html\n<mds-banner variant=\"dark\" tone=\"strong\" headline=\"Novita del mese\">\n <mds-text typography=\"detail\">\n Tre nuovi moduli sono stati aggiunti alla piattaforma.\n </mds-text>\n <mds-button slot=\"action\" variant=\"light\" tone=\"text\">Scopri</mds-button>\n</mds-banner>\n```\n\n#### AI Variant\n\nUse `variant=\"ai\"` to mark banners that present AI-generated content or AI-powered suggestions. The variant emits a polite `role=\"status\"` live announcement.\n\n```html\n<mds-banner variant=\"ai\" icon=\"mi/baseline/auto-awesome\" headline=\"Suggerimento IA\">\n <mds-text typography=\"detail\">\n L'analisi ha rilevato tre anomalie nel documento caricato.\n </mds-text>\n <mds-button slot=\"action\" variant=\"ai\" tone=\"outline\">Visualizza dettagli</mds-button>\n</mds-banner>\n```\n\n####
|
|
2327
|
-
"3. Mistakes": "Common incorrect uses of `<mds-banner>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use an Invalid `tone` Value\n\n`mds-banner.tone` is typed as `ToneMinimalBoxVariantType`, which allows only `weak`, `strong`, and `box`. Values like `outline` or `text` are not accepted: no tone style matches them, so the banner renders as with `strong`, not with the `weak` default.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"info\" tone=\"outline\">\n <mds-text typography=\"detail\">Informazione di sistema.</mds-text>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"info\" tone=\"weak\">\n <mds-text typography=\"detail\">Informazione di sistema.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Override the ARIA Role Manually\n\nThe component derives `role` and `aria-live` from `variant` (`error`/`warning` assertive, others polite) and writes them on the host when it renders, overwriting a manual value. To change the announcement, change the `variant`.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"info\" role=\"alert\" aria-live=\"assertive\">\n <mds-text typography=\"detail\">Aggiornamento disponibile.</mds-text>\n</mds-banner>\n\n<!-- CORRECT - let variant drive the ARIA behavior -->\n<mds-banner variant=\"info\">\n <mds-text typography=\"detail\">Aggiornamento disponibile.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Slot an `mds-button` into the Default Slot to Add Actions\n\nThe `action` named slot is the correct place for inline controls. Placing buttons in the default slot renders them inside the text region, breaks layout, and loses the flex wrapping the action row provides.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"warning\">\n <mds-text typography=\"detail\">La licenza sta per scadere.</mds-text>\n <mds-button variant=\"warning\">Rinnova</mds-button>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"warning\">\n <mds-text typography=\"detail\">La licenza sta per scadere.</mds-text>\n <mds-button slot=\"action\" variant=\"warning\" tone=\"strong\">Rinnova</mds-button>\n</mds-banner>\n```\n\n#### Do Not Set `dismissible=\"false\"` to Hide the Close Button\n\n`dismissible` is a boolean prop, and a false boolean is an absent attribute ([`agents/mistakes.md`](../../../../agents/mistakes.md)). Stencil reads the string `\"false\"` as `false` here, so the button is hidden, but the attribute stays on the element and any `[dismissible]` selector still matches it. Remove the attribute (or omit it) to hide the button.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"error\" dismissible=\"false\">\n <mds-text typography=\"detail\">Errore permanente - non dismissibile.</mds-text>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"error\">\n <mds-text typography=\"detail\">Errore permanente - non dismissibile.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Use `dark` or `light` for Status Messages\n\n`variant=\"dark\"` and `variant=\"light\"` produce `role=\"presentation\"` with no live region - they are silent to assistive tech. Using them for error, warning, or informational content means screen reader users never receive the announcement.\n\n```html\n<!-- INCORRECT - errore silenzioso per tecnologie assistive -->\n<mds-banner variant=\"dark\">\n <mds-text typography=\"detail\">Errore: impossibile caricare il documento.</mds-text>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"error\">\n <mds-text typography=\"detail\">Errore: impossibile caricare il documento.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Pierce Shadow DOM to Style Internals\n\nThe only supported customization surface is the public `--mds-banner-*` CSS custom properties plus the `::part(text)` shadow part. Targeting internal class names with `>>>` or undocumented `::part()` names couples your code to the implementation and breaks on minor releases.\n\n```css\n/* INCORRECT */\nmds-banner >>> .headline {\n font-size: 1.5rem;\n}\nmds-banner::part(content) {\n padding: 0;\n}\n\n/* CORRECT */\nmds-banner {\n --mds-banner-radius: var(--magma-radius-sm);\n}\nmds-banner::part(text) {\n line-height: 1.6;\n}\n```\n\n#### Do Not Listen to the Native `click` Event for Dismissal\n\nThe component fires `mdsBannerClose` only when the close button is activated (both pointer and keyboard). A native `click` listener on the host fires for a click anywhere in the banner, body text and action buttons included.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"info\" dismissible id=\"notice\">\n <mds-text typography=\"detail\">Avviso temporaneo.</mds-text>\n</mds-banner>\n<script>\n document.querySelector('#notice').addEventListener('click', () => {\n document.querySelector('#notice').remove();\n });\n</script>\n\n<!-- CORRECT -->\n<mds-banner variant=\"info\" dismissible id=\"notice\">\n <mds-text typography=\"detail\">Avviso temporaneo.</mds-text>\n</mds-banner>\n<script>\n document.querySelector('#notice').addEventListener('mdsBannerClose', () => {\n document.querySelector('#notice').remove();\n });\n</script>\n```\n"
|
|
2433
|
+
"1. Description": "The `<mds-banner>` web component is the Magma Design System surface for contextual, in-page messages - informational notices, status callouts, and alerts - pairing an optional icon, headline, body text, and inline actions inside a single themed box.\n\n#### Semantic Behavior\n\n- **Variant-driven ARIA**: The announcement role is derived from `variant`, not set manually. `error` and `warning` announce assertively (`role=\"alert\"`); `ai`, `info`, `primary`, and `success` announce politely (`role=\"status\"`); `light` and `dark` are decorative and silent.\n- **Headline as label**: When `headline` is set it also becomes the banner's accessible label.\n- **The headline follows its place**: in the page it is the title of a part, `h6`; as the window of a dialog (`slot=\"window\"` on a child of `mds-modal`) it is the title of the dialog, `h5`, above the `h6` of the parts and the groups of fields the dialog holds (`titles/part` and `titles/dialog` of the design language). A banner moved in or out of a modal after the load, or given the slot `window` there, takes the style of its new place.\n- **Dismissal**: When `dismissible` is true a close button is rendered; activating it emits `mdsBannerClose` and, if the banner sits inside an `mds-modal`, closes that modal.\n- **Localized close button**: The close button title is localized (el/en/es/it) from the host language.\n- **Action slot**: The `action` region is rendered only when a direct `[slot=\"action\"]` child is present, so banners without actions produce no empty container.\n\n- **The row of actions stacks when the banner is narrow**: under `--magma-container-actions` of its content (380px) every action of the `action` slot takes the full width, in the order of the row, the main action at the bottom (`actions/stacked`).\n- **Fields take the step below**: a neutral banner paints `surface-overlay`, so a field inside it paints `surface-default` (`--magma-field-fill`); a banner of a status with `tone=\"strong\"` paints a tint, and its fields keep `overlay`.\n\n#### Properties & Visual Configurations\n\nThis component uses the shared `variant` / `tone` ladders defined in [`agents/variants.md`](../../../../agents/variants.md); pick the `variant` according to the message's semantic weight, since it also governs the ARIA behavior described above. `tone` is limited to the minimal-box set (`'weak'`, `'strong'`, `'box'`), defaulting to `'weak'`.\n\n#### Other behavioral props\n\n- **`hideCockade`** (default `false`) removes the colored decorative badge wrapping the leading `icon`; set it for a flatter icon presentation.\n- **`typography`** writes the style of the headline instead of its place: `h6` or `h5`, nothing larger, since `h4` is too large for a banner. A value it does not know falls back to the style of the place. Left out, the style is the role of the title of the place (`part`, `dialog`), so a theme that moves the role moves the headline too.\n- **`icon`** is a Magma icon library slug shown at the top-left, surfaced as decorative.\n- **`dismissible`** shows the close button - choose it for transient or user-acknowledged messages rather than persistent context.\n- **`deletable`** is the old name of `dismissible`, deprecated: the button dismisses the message, it deletes nothing. It still works, and goes in the next major.\n- The **default slot** carries the body text/markup; the **`action` slot** holds inline controls, with `mds-button` the recommended element.\n",
|
|
2434
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-banner>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Informational Banner\n\nThe baseline usage. Provide `variant=\"info\"` and place the body copy in the default slot. The component derives `role=\"status\"` and `aria-live=\"polite\"` automatically from the variant.\n\n```html\n<mds-banner variant=\"info\">\n <mds-text typography=\"detail\">\n Il sistema e in manutenzione programmata dalle 22:00 alle 23:00.\n </mds-text>\n</mds-banner>\n```\n\n#### Status Variants\n\nPick the variant that matches the message's semantic weight. `error` and `warning` set `role=\"alert\"` with assertive live region; the others use `role=\"status\"` with polite announcement.\n\n```html\n<!-- Esito positivo -->\n<mds-banner variant=\"success\">\n <mds-text typography=\"detail\">Dati salvati correttamente.</mds-text>\n</mds-banner>\n\n<!-- Avviso non bloccante -->\n<mds-banner variant=\"warning\">\n <mds-text typography=\"detail\">La sessione scadra tra 5 minuti.</mds-text>\n</mds-banner>\n\n<!-- Errore bloccante -->\n<mds-banner variant=\"error\">\n <mds-text typography=\"detail\">Impossibile completare l'operazione. Riprovare.</mds-text>\n</mds-banner>\n```\n\n#### Banner with Headline\n\nUse the `headline` prop to add a title above the body text. The headline is also used as the banner's accessible label (`aria-label`).\n\n```html\n<mds-banner variant=\"warning\" headline=\"Licenza in scadenza\">\n <mds-text typography=\"detail\">\n La licenza del servizio scadra tra 7 giorni. Rinnova ora per non interrompere il servizio.\n </mds-text>\n</mds-banner>\n```\n\n#### Banner with Icon\n\nSet `icon` to a Magma icon slug. The icon is decorative (`aria-hidden=\"true\"`). The colored badge wrapping the icon is shown by default; add `hide-cockade` for a flatter look.\n\n```html\n<!-- Con cockade (default) -->\n<mds-banner variant=\"info\" icon=\"mi/baseline/info\" headline=\"Aggiornamento disponibile\">\n <mds-text typography=\"detail\">E disponibile una nuova versione dell'applicazione.</mds-text>\n</mds-banner>\n\n<!-- Senza cockade -->\n<mds-banner variant=\"success\" icon=\"mi/baseline/check-circle\" hide-cockade>\n <mds-text typography=\"detail\">Operazione completata.</mds-text>\n</mds-banner>\n```\n\n#### Dismissible Banner\n\nSet `dismissible` to show a close button. The button emits `mdsBannerClose` when activated. Listen for the event to remove the banner from the DOM or update application state.\n\n```html\n<mds-banner variant=\"info\" dismissible id=\"promo-banner\">\n <mds-text typography=\"detail\">\n Scopri le nuove funzioni premium disponibili nel tuo piano.\n </mds-text>\n</mds-banner>\n\n<script>\n document.querySelector('#promo-banner').addEventListener('mdsBannerClose', () => {\n document.querySelector('#promo-banner').remove();\n });\n</script>\n```\n\n#### Banner with Action Buttons\n\nSlot `<mds-button>` elements with `slot=\"action\"` to add inline controls. The action region is shown only while at least one `[slot=\"action\"]` child is present, and it follows the actions added or removed after the first render. Match the button variant to the banner variant for visual consistency.\n\n```html\n<mds-banner variant=\"warning\" headline=\"Abbonamento scaduto\">\n <mds-text typography=\"detail\">\n La licenza di questo servizio e scaduta. Il servizio continua a funzionare\n ma non puoi utilizzare le funzioni premium.\n </mds-text>\n <mds-button slot=\"action\" variant=\"warning\" tone=\"outline\">Annulla</mds-button>\n <mds-button slot=\"action\" variant=\"warning\" tone=\"strong\">Rinnova abbonamento</mds-button>\n</mds-banner>\n```\n\n#### Tone for Visual Emphasis\n\n`tone` controls emphasis without changing the semantic variant. `strong` paints the status tint on the whole banner, `weak` (default) keeps a neutral raised surface and colours only the icon, and `box` adds a solid box shadow for high-contrast placements. `mds-banner` accepts only `weak`, `strong`, and `box` - not `outline` or `text`.\n\n```html\n<!-- Bassa enfasi (default) -->\n<mds-banner variant=\"error\" tone=\"weak\">\n <mds-text typography=\"detail\">Errore di validazione nei campi del modulo.</mds-text>\n</mds-banner>\n\n<!-- Alta enfasi -->\n<mds-banner variant=\"error\" tone=\"strong\">\n <mds-text typography=\"detail\">Account bloccato per attivita sospetta. Contatta il supporto.</mds-text>\n</mds-banner>\n```\n\n#### Dark and Light Decorative Variants\n\n`variant=\"dark\"` and `variant=\"light\"` are neutral, decorative banners without an ARIA live region (`role=\"presentation\"`). Use them for non-critical UI chrome - announcements or promotional content that does not require immediate attention.\n\n```html\n<mds-banner variant=\"dark\" tone=\"strong\" headline=\"Novita del mese\">\n <mds-text typography=\"detail\">\n Tre nuovi moduli sono stati aggiunti alla piattaforma.\n </mds-text>\n <mds-button slot=\"action\" variant=\"light\" tone=\"text\">Scopri</mds-button>\n</mds-banner>\n```\n\n#### AI Variant\n\nUse `variant=\"ai\"` to mark banners that present AI-generated content or AI-powered suggestions. The variant emits a polite `role=\"status\"` live announcement.\n\n```html\n<mds-banner variant=\"ai\" icon=\"mi/baseline/auto-awesome\" headline=\"Suggerimento IA\">\n <mds-text typography=\"detail\">\n L'analisi ha rilevato tre anomalie nel documento caricato.\n </mds-text>\n <mds-button slot=\"action\" variant=\"ai\" tone=\"outline\">Visualizza dettagli</mds-button>\n</mds-banner>\n```\n\n#### The Window of a Dialog\n\nSlotted as the `window` of an `<mds-modal>`, the banner is the dialog: `variant=\"light\"` `tone=\"box\"` `dismissible`, its close button closes the modal with no extra JavaScript, and its headline is the title of the dialog, in `h5`, with no attribute to write. The headline is hidden from screen readers, so `aria-label` on `mds-modal` names the dialog, with the same text.\n\n```html\n<mds-modal aria-label=\"Eliminare Contratto di servizio?\">\n <mds-banner slot=\"window\" variant=\"light\" tone=\"box\" dismissible headline=\"Eliminare Contratto di servizio?\">\n <mds-text typography=\"detail\">Il documento non potra' essere recuperato.</mds-text>\n <mds-button slot=\"action\" variant=\"dark\" tone=\"outline\" autofocus>Annulla</mds-button>\n <mds-button slot=\"action\" variant=\"error\" tone=\"strong\">Elimina</mds-button>\n </mds-banner>\n</mds-modal>\n```\n\nIn the page the same banner keeps its headline in `h6`, the title of a part. `typography` writes the style when the place does not say it: `h6` or `h5`, nothing larger.\n\n```html\n<mds-banner variant=\"info\" typography=\"h5\" headline=\"Nuova versione del servizio\">\n <mds-text typography=\"detail\">Da oggi puoi firmare i documenti dall'app.</mds-text>\n</mds-banner>\n```\n\n#### CSS Custom Property Customization\n\nOverride appearance only through the public `--mds-banner-*` custom properties. Set them on the host or a parent selector; use semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.featured-notice mds-banner {\n --mds-banner-background: rgb(var(--magma-accent-emphasis));\n --mds-banner-color: rgb(var(--magma-accent-on-emphasis));\n --mds-banner-radius: var(--magma-radius-sm);\n --mds-banner-shadow: 0 4px 16px rgb(var(--magma-shadow-ink) / 0.15);\n}\n```\n",
|
|
2435
|
+
"3. Mistakes": "Common incorrect uses of `<mds-banner>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use an Invalid `tone` Value\n\n`mds-banner.tone` is typed as `ToneMinimalBoxVariantType`, which allows only `weak`, `strong`, and `box`. Values like `outline` or `text` are not accepted: no tone style matches them, so the banner renders as with `strong`, not with the `weak` default.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"info\" tone=\"outline\">\n <mds-text typography=\"detail\">Informazione di sistema.</mds-text>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"info\" tone=\"weak\">\n <mds-text typography=\"detail\">Informazione di sistema.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Ask the Headline for a Style Larger Than `h5`\n\n`typography` takes `h6` and `h5` only: a value it does not know, such as `h4`, falls back to the style of the place. A title written in the default slot instead of `headline` is no headline either: it is not the accessible label of the banner, and it keeps its style wherever the banner goes. Write the title in `headline` and leave its style to the place, or write `h6` or `h5`.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"info\" typography=\"h4\" headline=\"Nuovo servizio\">\n <mds-text typography=\"detail\">Da oggi puoi firmare i documenti dall'app.</mds-text>\n</mds-banner>\n<mds-banner variant=\"info\">\n <mds-text typography=\"h4\">Nuovo servizio</mds-text>\n <mds-text typography=\"detail\">Da oggi puoi firmare i documenti dall'app.</mds-text>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"info\" headline=\"Nuovo servizio\">\n <mds-text typography=\"detail\">Da oggi puoi firmare i documenti dall'app.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Override the ARIA Role Manually\n\nThe component derives `role` and `aria-live` from `variant` (`error`/`warning` assertive, others polite) and writes them on the host when it renders, overwriting a manual value. To change the announcement, change the `variant`.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"info\" role=\"alert\" aria-live=\"assertive\">\n <mds-text typography=\"detail\">Aggiornamento disponibile.</mds-text>\n</mds-banner>\n\n<!-- CORRECT - let variant drive the ARIA behavior -->\n<mds-banner variant=\"info\">\n <mds-text typography=\"detail\">Aggiornamento disponibile.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Slot an `mds-button` into the Default Slot to Add Actions\n\nThe `action` named slot is the correct place for inline controls. Placing buttons in the default slot renders them inside the text region, breaks layout, and loses the flex wrapping the action row provides.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"warning\">\n <mds-text typography=\"detail\">La licenza sta per scadere.</mds-text>\n <mds-button variant=\"warning\">Rinnova</mds-button>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"warning\">\n <mds-text typography=\"detail\">La licenza sta per scadere.</mds-text>\n <mds-button slot=\"action\" variant=\"warning\" tone=\"strong\">Rinnova</mds-button>\n</mds-banner>\n```\n\n#### Do Not Set `dismissible=\"false\"` to Hide the Close Button\n\n`dismissible` is a boolean prop, and a false boolean is an absent attribute ([`agents/mistakes.md`](../../../../agents/mistakes.md)). Stencil reads the string `\"false\"` as `false` here, so the button is hidden, but the attribute stays on the element and any `[dismissible]` selector still matches it. Remove the attribute (or omit it) to hide the button.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"error\" dismissible=\"false\">\n <mds-text typography=\"detail\">Errore permanente - non dismissibile.</mds-text>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"error\">\n <mds-text typography=\"detail\">Errore permanente - non dismissibile.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Use `dark` or `light` for Status Messages\n\n`variant=\"dark\"` and `variant=\"light\"` produce `role=\"presentation\"` with no live region - they are silent to assistive tech. Using them for error, warning, or informational content means screen reader users never receive the announcement.\n\n```html\n<!-- INCORRECT - errore silenzioso per tecnologie assistive -->\n<mds-banner variant=\"dark\">\n <mds-text typography=\"detail\">Errore: impossibile caricare il documento.</mds-text>\n</mds-banner>\n\n<!-- CORRECT -->\n<mds-banner variant=\"error\">\n <mds-text typography=\"detail\">Errore: impossibile caricare il documento.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Pierce Shadow DOM to Style Internals\n\nThe only supported customization surface is the public `--mds-banner-*` CSS custom properties plus the `::part(text)` shadow part. Targeting internal class names with `>>>` or undocumented `::part()` names couples your code to the implementation and breaks on minor releases.\n\n```css\n/* INCORRECT */\nmds-banner >>> .headline {\n font-size: 1.5rem;\n}\nmds-banner::part(content) {\n padding: 0;\n}\n\n/* CORRECT */\nmds-banner {\n --mds-banner-radius: var(--magma-radius-sm);\n}\nmds-banner::part(text) {\n line-height: 1.6;\n}\n```\n\n#### Do Not Listen to the Native `click` Event for Dismissal\n\nThe component fires `mdsBannerClose` only when the close button is activated (both pointer and keyboard). A native `click` listener on the host fires for a click anywhere in the banner, body text and action buttons included.\n\n```html\n<!-- INCORRECT -->\n<mds-banner variant=\"info\" dismissible id=\"notice\">\n <mds-text typography=\"detail\">Avviso temporaneo.</mds-text>\n</mds-banner>\n<script>\n document.querySelector('#notice').addEventListener('click', () => {\n document.querySelector('#notice').remove();\n });\n</script>\n\n<!-- CORRECT -->\n<mds-banner variant=\"info\" dismissible id=\"notice\">\n <mds-text typography=\"detail\">Avviso temporaneo.</mds-text>\n</mds-banner>\n<script>\n document.querySelector('#notice').addEventListener('mdsBannerClose', () => {\n document.querySelector('#notice').remove();\n });\n</script>\n```\n"
|
|
2328
2436
|
},
|
|
2329
2437
|
"props": [
|
|
2330
2438
|
{
|
|
@@ -2517,6 +2625,44 @@
|
|
|
2517
2625
|
"getter": false,
|
|
2518
2626
|
"setter": false
|
|
2519
2627
|
},
|
|
2628
|
+
{
|
|
2629
|
+
"name": "typography",
|
|
2630
|
+
"type": "\"h5\" | \"h6\" | undefined",
|
|
2631
|
+
"complexType": {
|
|
2632
|
+
"original": "BannerTypographyType",
|
|
2633
|
+
"resolved": "\"h5\" | \"h6\" | undefined",
|
|
2634
|
+
"references": {
|
|
2635
|
+
"BannerTypographyType": {
|
|
2636
|
+
"location": "import",
|
|
2637
|
+
"path": "./meta/types",
|
|
2638
|
+
"id": "src/components/mds-banner/meta/types.ts::BannerTypographyType",
|
|
2639
|
+
"referenceLocation": "BannerTypographyType"
|
|
2640
|
+
}
|
|
2641
|
+
}
|
|
2642
|
+
},
|
|
2643
|
+
"mutable": false,
|
|
2644
|
+
"attr": "typography",
|
|
2645
|
+
"reflectToAttr": false,
|
|
2646
|
+
"docs": "The style of the headline: `h6`, the title of a part, or `h5`, the title of a dialog\n(#1189, titles). Left out, it follows the place of the banner: `h6` in the page, `h5` as\nthe window of a dialog (`slot=\"window\"` on a child of `mds-modal`), above the `h6` of the\nparts and the groups of fields it holds. Nothing larger: `h4` is too large for a banner",
|
|
2647
|
+
"docsTags": [],
|
|
2648
|
+
"values": [
|
|
2649
|
+
{
|
|
2650
|
+
"value": "h5",
|
|
2651
|
+
"type": "string"
|
|
2652
|
+
},
|
|
2653
|
+
{
|
|
2654
|
+
"value": "h6",
|
|
2655
|
+
"type": "string"
|
|
2656
|
+
},
|
|
2657
|
+
{
|
|
2658
|
+
"type": "undefined"
|
|
2659
|
+
}
|
|
2660
|
+
],
|
|
2661
|
+
"optional": true,
|
|
2662
|
+
"required": false,
|
|
2663
|
+
"getter": false,
|
|
2664
|
+
"setter": false
|
|
2665
|
+
},
|
|
2520
2666
|
{
|
|
2521
2667
|
"name": "variant",
|
|
2522
2668
|
"type": "\"ai\" | \"dark\" | \"error\" | \"info\" | \"light\" | \"primary\" | \"success\" | \"warning\" | undefined",
|
|
@@ -5356,8 +5502,8 @@
|
|
|
5356
5502
|
}
|
|
5357
5503
|
],
|
|
5358
5504
|
"usage": {
|
|
5359
|
-
"1. Description": "The `<mds-button-dropdown>` web component is a split-button control of the Magma Design System: it pairs a primary `<mds-button>` action with a secondary chevron button that opens an attached `<mds-dropdown>`, giving users a default action plus a menu of related choices in a single, visually unified control.\n\n#### Semantic Behavior\n\n- **Default slot is the menu**: Whatever you place in the default slot becomes the dropdown panel content; it is not treated as the button label (the visible label comes from the `label` prop).\n- **Chevron trigger**: The second button is icon-only (chevron), named in the page language (the `lang` of `<html>`) (\"More actions\"), and toggles the dropdown; it carries `aria-haspopup` and `aria-expanded` for the menu it opens.\n- **Shared configuration**: `active`, `await`, `disabled`, `size`, `tone` and `variant` are forwarded identically to both internal buttons, so the two halves always stay visually and behaviorally in sync. `href`, `target` and `autoFocus` belong to the primary action alone: the chevron only opens the menu.\n- **Current state**: `current` marks the primary action as the one that leads to the view you are in, as on `<mds-button>`. Both halves take the look of the current button; only the primary action is announced with `aria-current` and, with `current` (or `current=\"page\"`), neither navigates, nor submits, nor fires `mdsButtonDropdownClick`. With `current=\"section\"`, a view inside it, the primary action stays a link back. The chevron keeps opening the menu either way. A menu item that leads to the view you are in takes `current` itself.\n- **Form association**: The host is form-associated. With `type=\"submit\"` the primary action submits the enclosing `<form>` (or the one its `form` attribute names) and sends `name=value`, like a native submit button; with `type=\"reset\"` it resets it. The chevron never submits. Unlike `<mds-button>`, `type` defaults to `'button'`: a dropdown in a form submits it only when asked. The menu items are slotted `<mds-button>`, so they follow their own `type` (default `'submit'`), `name` and `value`, and the receiver tells all the actions apart by `name`.\n- **Disabled / await states**: Because these flags pass through to both buttons, disabling or putting the control in an awaiting state affects the action and the trigger together. A disabled `<fieldset>` around the component disables both halves the same way, without setting `disabled`.\n- **Primary action event**: `mdsButtonDropdownClick` fires when the primary action is clicked or activated from the keyboard, and not while the component is `disabled` or awaiting. The chevron and the menu items do not fire it. A native `click` listener on the component also runs for the menu items, whose clicks bubble to it, so listen for `mdsButtonDropdownClick` to run the primary action in JavaScript.\n- **Dropdown part**: The internal dropdown is exposed as the `dropdown` shadow part for external styling of the menu surface.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` / `tone` / `size` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md); they apply here as in `<mds-button>`, narrowed to `tone` `strong` / `weak` and without the `google` / `apple` variants, and are forwarded to both internal buttons. `variant` defaults to `'primary'`, `tone` defaults to `'strong'`, and `size` defaults to `'md'`.\n\n- **`label`** sets the text of the primary action button only; the chevron trigger is icon-only.\n- **`type`** (default `'button'`), **`name`** and **`value`** apply to the primary action only, as described under Form association. The menu items follow their own `type`: inside a `<form>`, give `type=\"button\"` to the ones that must not submit it.\n- **`href`** makes the primary action a link that navigates instead of submitting, with `target` choosing `'self'` vs `'blank'`; the chevron still opens the menu.\n\n#### Other behavioral props\n\n- **`autoFocus`** focuses the primary action once the component is loaded.\n- **`icon`** is an SVG filename slug from the Magma icon library, applied to the primary action button (the chevron icon on the trigger is fixed and not configurable).\n- **`iconCurrent`** and **`iconHover`** take the place of `icon` on the primary action, when it is current and under the pointer, as on `<mds-button>`: `iconHover` falls back on `iconCurrent`, and both need `icon`. The chevron keeps its arrow.\n- **`truncate`** sets how the label of the primary action truncates, as on `mds-button` (default `'word'`).\n",
|
|
5360
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-button-dropdown>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Split Button with Menu Items\n\nThe canonical form: a `label` prop for the primary action and one or more [`mds-button`](../mds-button/AGENTS.md) elements in the default slot as menu choices. Give the slot items `variant=\"dark\" tone=\"text\"` to keep them visually neutral inside the dropdown panel.\n\n```html\n<mds-button-dropdown label=\"Salva come bozza\" variant=\"success\" tone=\"weak\">\n <mds-button icon=\"mi/baseline/send\" variant=\"dark\" tone=\"text\" label=\"Invia subito\"></mds-button>\n <mds-button icon=\"mi/baseline/delete\" variant=\"dark\" tone=\"text\" label=\"Elimina\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Variant and Tone for Emphasis\n\nUse `variant` to express meaning and `tone` to express weight - the same pair applies to both internal buttons automatically.\n\n```html\n<!-- High emphasis: primary action -->\n<mds-button-dropdown label=\"Pubblica\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Pubblica come bozza\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Pianifica pubblicazione\"></mds-button>\n</mds-button-dropdown>\n\n<!-- Status emphasis: destructive action group -->\n<mds-button-dropdown label=\"Elimina voce\" variant=\"error\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Elimina e archivia\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Annulla eliminazione\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Sizing\n\nUse the `size` prop. Both internal buttons track it automatically.\n\n```html\n<mds-button-dropdown label=\"Azione\" size=\"sm\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"md\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"lg\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"xl\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Primary Action with an Icon\n\nSupply the `icon` prop to add an icon to the primary action button. The chevron trigger icon is fixed and not configurable.\n\n```html\n<mds-button-dropdown\n label=\"Carica documento\"\n icon=\"mi/baseline/upload\"\n variant=\"primary\"\n tone=\"weak\"\n>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Carica da URL\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Carica da Drive\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while a request is in flight. Both the action button and the chevron trigger become unavailable simultaneously. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-button-dropdown label=\"Salvataggio in corso...\" await variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Salva e chiudi\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Salva come copia\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Disabled State\n\nThe `disabled` attribute blocks both halves of the control together.\n\n```html\n<mds-button-dropdown label=\"Invia richiesta\" disabled variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Invia in bozza\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Primary Action Handled in JavaScript\n\nListen for `mdsButtonDropdownClick` to run the primary action: it comes from the primary action only, from a click or the keyboard, and not while the component is `disabled` or awaiting. Handle each menu item with its own `click`.\n\n```html\n<mds-button-dropdown id=\"save\" label=\"Salva\" variant=\"primary\">\n <mds-button id=\"save-copy\" variant=\"dark\" tone=\"text\" label=\"Salva come copia\"></mds-button>\n</mds-button-dropdown>\n\n<script>\n document.getElementById('save').addEventListener('mdsButtonDropdownClick', () => save());\n document.getElementById('save-copy').addEventListener('click', () => saveCopy());\n</script>\n```\n\n#### Several Actions That Submit One Form\n\nSet `type=\"submit\"` on the component and give the primary action and the menu items the same `name` with a different `value`: each action submits the form, and the receiver reads which one was chosen from `name`, as with native submit buttons. Give `type=\"button\"` to the menu items that must not submit.\n\n```html\n<form action=\"/mail\" method=\"post\">\n <mds-input-field label=\"Oggetto\">\n <mds-input name=\"subject\"></mds-input>\n </mds-input-field>\n\n <!-- the receiver gets action=send, action=draft or action=schedule -->\n <mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\" variant=\"primary\">\n <mds-button name=\"action\" value=\"draft\" variant=\"dark\" tone=\"text\" label=\"Salva come bozza\"></mds-button>\n <mds-button name=\"action\" value=\"schedule\" variant=\"dark\" tone=\"text\" label=\"Invio programmato\"></mds-button>\n <mds-button type=\"button\" variant=\"dark\" tone=\"text\" label=\"Anteprima\"></mds-button>\n </mds-button-dropdown>\n</form>\n```\n\nWhen your code handles the submit, build the form data with `event.submitter`, as for [`mds-button`](../mds-button/AGENTS.md): `new FormData(form, event.submitter)`.\n\n#### Hyperlink Split Button via `href`\n\n`href` and `target` on the component make the primary action a link; the chevron keeps opening the menu. Put the other links on the menu items (`target=\"blank\"` opens them in a new tab).\n\n```html\n<mds-button-dropdown\n label=\"Apri documento\"\n href=\"https://example.com/doc\"\n variant=\"primary\"\n tone=\"weak\"\n>\n <mds-button href=\"https://example.com/doc/edit\" target=\"blank\" variant=\"dark\" tone=\"text\" label=\"Modifica\"></mds-button>\n <mds-button href=\"https://example.com/doc/history\" target=\"blank\" variant=\"dark\" tone=\"text\" label=\"Cronologia\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Styling Customization\n\nStyle the component through its documented `--mds-button-dropdown-*` CSS custom properties or the `dropdown` shadow part. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and named themes keep working.\n\nThe `--mds-button-*` properties that inherit reach the two inner buttons too: `--mds-button-label-transform: none` on the component keeps a label such as a tenant name as written, without the uppercase first letter.\n\n```css\n.custom-toolbar mds-button-dropdown {\n --mds-button-dropdown-radius: var(--magma-radius-md);\n}\n\n.tenant-switcher mds-button-dropdown {\n --mds-button-label-transform: none;\n}\n\n/* Style the dropdown panel surface through the documented shadow part */\n.custom-toolbar mds-button-dropdown::part(dropdown) {\n box-shadow: var(--shadow-lg);\n}\n```\n",
|
|
5505
|
+
"1. Description": "The `<mds-button-dropdown>` web component is a split-button control of the Magma Design System: it pairs a primary `<mds-button>` action with a secondary chevron button that opens an attached `<mds-dropdown>`, giving users a default action plus a menu of related choices in a single, visually unified control.\n\n#### Semantic Behavior\n\n- **Default slot is the menu**: Whatever you place in the default slot becomes the dropdown panel content; it is not treated as the button label (the visible label comes from the `label` prop).\n- **Chevron trigger**: The second button is icon-only (chevron), named in the page language (the `lang` of `<html>`) (\"More actions\"), and toggles the dropdown; it carries `aria-haspopup` and `aria-expanded` for the menu it opens.\n- **Shared configuration**: `active`, `await`, `disabled`, `size`, `tone` and `variant` are forwarded identically to both internal buttons, so the two halves always stay visually and behaviorally in sync. `href`, `target` and `autoFocus` belong to the primary action alone: the chevron only opens the menu.\n- **Current state**: `current` marks the primary action as the one that leads to the view you are in, as on `<mds-button>`. Both halves take the look of the current button; only the primary action is announced with `aria-current` and, with `current` (or `current=\"page\"`), neither navigates, nor submits, nor fires `mdsButtonDropdownClick`. With `current=\"section\"`, a view inside it, the primary action stays a link back. The chevron keeps opening the menu either way. A menu item that leads to the view you are in takes `current` itself.\n- **Form association**: The host is form-associated. With `type=\"submit\"` the primary action submits the enclosing `<form>` (or the one its `form` attribute names) and sends `name=value`, like a native submit button; with `type=\"reset\"` it resets it. The chevron never submits. Unlike `<mds-button>`, `type` defaults to `'button'`: a dropdown in a form submits it only when asked. The menu items are slotted `<mds-button>`, so they follow their own `type` (default `'submit'`), `name` and `value`, and the receiver tells all the actions apart by `name`.\n- **Disabled / await states**: Because these flags pass through to both buttons, disabling or putting the control in an awaiting state affects the action and the trigger together. A disabled `<fieldset>` around the component disables both halves the same way, without setting `disabled`.\n- **Primary action event**: `mdsButtonDropdownClick` fires when the primary action is clicked or activated from the keyboard, and not while the component is `disabled` or awaiting. The chevron and the menu items do not fire it. A native `click` listener on the component also runs for the menu items, whose clicks bubble to it, so listen for `mdsButtonDropdownClick` to run the primary action in JavaScript.\n- **Dropdown part**: The internal dropdown is exposed as the `dropdown` shadow part for external styling of the menu surface.\n- **Corners**: The two halves take their outer corners from the host, the radius of `--mds-button-dropdown-radius`, and meet with flat inner corners. A row that joins the component flattens its corners on the host: in an `<mds-button-group>` the side that touches the next member is flat, on the primary action or on the chevron.\n- **Width**: The component keeps its own width, its primary action as wide as an `<mds-button>` with the same label. A row that stretches it, as `actions/stacked` does under `--magma-container-actions` (380px) in `<mds-card-footer>`, `<mds-banner>`, `<mds-status-bar>` or a row of your own (`align-self: stretch`, a `width`, a `flex-basis`), gives the free width to the primary action, its label in the middle, and keeps the chevron at its own size at the end: the two halves still read as one button, with no fill past them.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` / `tone` / `size` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md); they apply here as in `<mds-button>`, narrowed to `tone` `strong` / `weak` and without the `google` / `apple` variants, and are forwarded to both internal buttons. `variant` defaults to `'primary'`, `tone` defaults to `'strong'`, and `size` defaults to `'md'`.\n\n- **`label`** sets the text of the primary action button only; the chevron trigger is icon-only.\n- **`type`** (default `'button'`), **`name`** and **`value`** apply to the primary action only, as described under Form association. The menu items follow their own `type`: inside a `<form>`, give `type=\"button\"` to the ones that must not submit it.\n- **`href`** makes the primary action a link that navigates instead of submitting, with `target` choosing `'self'` vs `'blank'`; the chevron still opens the menu.\n\n#### Other behavioral props\n\n- **`autoFocus`** focuses the primary action once the component is loaded.\n- **`icon`** is an SVG filename slug from the Magma icon library, applied to the primary action button (the chevron icon on the trigger is fixed and not configurable).\n- **`iconCurrent`** and **`iconHover`** take the place of `icon` on the primary action, when it is current and under the pointer, as on `<mds-button>`: `iconHover` falls back on `iconCurrent`, and both need `icon`. The chevron keeps its arrow.\n- **`truncate`** sets how the label of the primary action truncates, as on `mds-button` (default `'word'`).\n",
|
|
5506
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-button-dropdown>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Split Button with Menu Items\n\nThe canonical form: a `label` prop for the primary action and one or more [`mds-button`](../mds-button/AGENTS.md) elements in the default slot as menu choices. Give the slot items `variant=\"dark\" tone=\"text\"` to keep them visually neutral inside the dropdown panel.\n\n```html\n<mds-button-dropdown label=\"Salva come bozza\" variant=\"success\" tone=\"weak\">\n <mds-button icon=\"mi/baseline/send\" variant=\"dark\" tone=\"text\" label=\"Invia subito\"></mds-button>\n <mds-button icon=\"mi/baseline/delete\" variant=\"dark\" tone=\"text\" label=\"Elimina\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Variant and Tone for Emphasis\n\nUse `variant` to express meaning and `tone` to express weight - the same pair applies to both internal buttons automatically.\n\n```html\n<!-- High emphasis: primary action -->\n<mds-button-dropdown label=\"Pubblica\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Pubblica come bozza\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Pianifica pubblicazione\"></mds-button>\n</mds-button-dropdown>\n\n<!-- Status emphasis: destructive action group -->\n<mds-button-dropdown label=\"Elimina voce\" variant=\"error\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Elimina e archivia\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Annulla eliminazione\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Sizing\n\nUse the `size` prop. Both internal buttons track it automatically.\n\n```html\n<mds-button-dropdown label=\"Azione\" size=\"sm\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"md\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"lg\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n\n<mds-button-dropdown label=\"Azione\" size=\"xl\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione A\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Primary Action with an Icon\n\nSupply the `icon` prop to add an icon to the primary action button. The chevron trigger icon is fixed and not configurable.\n\n```html\n<mds-button-dropdown\n label=\"Carica documento\"\n icon=\"mi/baseline/upload\"\n variant=\"primary\"\n tone=\"weak\"\n>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Carica da URL\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Carica da Drive\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while a request is in flight. Both the action button and the chevron trigger become unavailable simultaneously. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-button-dropdown label=\"Salvataggio in corso...\" await variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Salva e chiudi\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Salva come copia\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Disabled State\n\nThe `disabled` attribute blocks both halves of the control together.\n\n```html\n<mds-button-dropdown label=\"Invia richiesta\" disabled variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Invia in bozza\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Primary Action Handled in JavaScript\n\nListen for `mdsButtonDropdownClick` to run the primary action: it comes from the primary action only, from a click or the keyboard, and not while the component is `disabled` or awaiting. Handle each menu item with its own `click`.\n\n```html\n<mds-button-dropdown id=\"save\" label=\"Salva\" variant=\"primary\">\n <mds-button id=\"save-copy\" variant=\"dark\" tone=\"text\" label=\"Salva come copia\"></mds-button>\n</mds-button-dropdown>\n\n<script>\n document.getElementById('save').addEventListener('mdsButtonDropdownClick', () => save());\n document.getElementById('save-copy').addEventListener('click', () => saveCopy());\n</script>\n```\n\n#### Several Actions That Submit One Form\n\nSet `type=\"submit\"` on the component and give the primary action and the menu items the same `name` with a different `value`: each action submits the form, and the receiver reads which one was chosen from `name`, as with native submit buttons. Give `type=\"button\"` to the menu items that must not submit.\n\n```html\n<form action=\"/mail\" method=\"post\">\n <mds-input-field label=\"Oggetto\">\n <mds-input name=\"subject\"></mds-input>\n </mds-input-field>\n\n <!-- the receiver gets action=send, action=draft or action=schedule -->\n <mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\" variant=\"primary\">\n <mds-button name=\"action\" value=\"draft\" variant=\"dark\" tone=\"text\" label=\"Salva come bozza\"></mds-button>\n <mds-button name=\"action\" value=\"schedule\" variant=\"dark\" tone=\"text\" label=\"Invio programmato\"></mds-button>\n <mds-button type=\"button\" variant=\"dark\" tone=\"text\" label=\"Anteprima\"></mds-button>\n </mds-button-dropdown>\n</form>\n```\n\nWhen your code handles the submit, build the form data with `event.submitter`, as for [`mds-button`](../mds-button/AGENTS.md): `new FormData(form, event.submitter)`.\n\n#### Hyperlink Split Button via `href`\n\n`href` and `target` on the component make the primary action a link; the chevron keeps opening the menu. Put the other links on the menu items (`target=\"blank\"` opens them in a new tab).\n\n```html\n<mds-button-dropdown\n label=\"Apri documento\"\n href=\"https://example.com/doc\"\n variant=\"primary\"\n tone=\"weak\"\n>\n <mds-button href=\"https://example.com/doc/edit\" target=\"blank\" variant=\"dark\" tone=\"text\" label=\"Modifica\"></mds-button>\n <mds-button href=\"https://example.com/doc/history\" target=\"blank\" variant=\"dark\" tone=\"text\" label=\"Cronologia\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### In a Row of Actions That Stacks\n\nStretch the component as any other action of the row: under `--magma-container-actions` of its container (`@max-actions:`), `actions/stacked` puts every labelled button at the full width, and the component gives that width to its primary action, the chevron staying at the end. No part or custom property is needed.\n\n```html\n<div class=\"@container\">\n <div class=\"flex justify-end gap-inline @max-actions:flex-col @max-actions:*:self-stretch\">\n <mds-button variant=\"dark\" tone=\"outline\" label=\"Copia JSON\"></mds-button>\n <mds-button-dropdown label=\"Scarica\" icon=\"mi/baseline/download\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Scarica come CSS\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Scarica come JSON\"></mds-button>\n </mds-button-dropdown>\n </div>\n</div>\n```\n\n#### Styling Customization\n\nStyle the component through its documented `--mds-button-dropdown-*` CSS custom properties or the `dropdown` shadow part. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and named themes keep working.\n\nThe `--mds-button-*` properties that inherit reach the two inner buttons too: `--mds-button-label-transform: none` on the component keeps a label such as a tenant name as written, without the uppercase first letter.\n\n```css\n.custom-toolbar mds-button-dropdown {\n --mds-button-dropdown-radius: var(--magma-radius-md);\n}\n\n.tenant-switcher mds-button-dropdown {\n --mds-button-label-transform: none;\n}\n\n/* Style the dropdown panel surface through the documented shadow part */\n.custom-toolbar mds-button-dropdown::part(dropdown) {\n box-shadow: var(--shadow-lg);\n}\n```\n",
|
|
5361
5507
|
"3. Mistakes": "Common incorrect uses of `<mds-button-dropdown>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Put the Label in the Default Slot\n\nThe default slot feeds the `<mds-dropdown>` panel, not the button label. Text placed in the slot ends up as menu content, not as the button's visible text. Use the `label` prop.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown variant=\"primary\" tone=\"strong\">\n Salva\n</mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown label=\"Salva\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Salva come bozza\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Slot Non-Button Content as Menu Items\n\nThe dropdown panel is designed for [`mds-button`](../mds-button/AGENTS.md) elements. Slotting raw `<button>`, `<a>`, or arbitrary HTML bypasses the Magma theming, focus styles and button API (`icon`, `await`, `disabled`) of the menu entries.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown label=\"Esporta\" variant=\"primary\" tone=\"weak\">\n <button onclick=\"exportPDF()\">PDF</button>\n <a href=\"/export/csv\">CSV</a>\n</mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown label=\"Esporta\" variant=\"primary\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Esporta PDF\" icon=\"mi/baseline/picture-as-pdf\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Esporta CSV\" icon=\"mi/baseline/table-chart\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Count on the Default `type` to Submit a Form\n\nUnlike `<mds-button>`, the component defaults to `type=\"button\"`: inside a form, the primary action submits nothing until you set `type=\"submit\"`.\n\n```html\n<!-- INCORRECT: the primary action does not submit -->\n<form action=\"/mail\" method=\"post\">\n <mds-button-dropdown name=\"action\" value=\"send\" label=\"Invia\">\n <mds-button name=\"action\" value=\"draft\" variant=\"dark\" tone=\"text\" label=\"Salva come bozza\"></mds-button>\n </mds-button-dropdown>\n</form>\n\n<!-- CORRECT -->\n<form action=\"/mail\" method=\"post\">\n <mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\">\n <mds-button name=\"action\" value=\"draft\" variant=\"dark\" tone=\"text\" label=\"Salva come bozza\"></mds-button>\n </mds-button-dropdown>\n</form>\n```\n\n#### Do Not Submit the Form from a `click` Listener\n\nA `click` listener on the component also runs for the menu items, whose clicks bubble to it: picking a menu item that submits (\"Salva come bozza\") submits the form twice, once with its `name` / `value` and once without, and the receiver cannot tell which action was chosen. Use `type=\"submit\"` with `name` / `value`.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown id=\"send\" label=\"Invia\"></mds-button-dropdown>\n<script>\n document.getElementById('send').addEventListener('click', () => form.requestSubmit());\n</script>\n\n<!-- CORRECT -->\n<mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\"></mds-button-dropdown>\n```\n\n#### Do Not Listen to `click` for the Primary Action\n\nA `click` on the component also comes from the menu items, whose clicks bubble to it: the primary action would run whenever the user picks an entry of the menu. Listen for `mdsButtonDropdownClick`, which only the primary action emits.\n\n```js\n// INCORRECT: also runs for \"Salva come copia\"\ndropdown.addEventListener('click', () => save());\n\n// CORRECT\ndropdown.addEventListener('mdsButtonDropdownClick', () => save());\n```\n\n#### Do Not Leave a Menu Item That Must Not Submit on the Default `type`\n\nThe menu items are slotted `<mds-button>`, whose `type` defaults to `'submit'`: inside a form, an item that runs your own code (a preview, a copy) submits the form too. Give it `type=\"button\"`.\n\n```html\n<!-- INCORRECT: \"Anteprima\" submits the form -->\n<mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Anteprima\"></mds-button>\n</mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown type=\"submit\" name=\"action\" value=\"send\" label=\"Invia\">\n <mds-button type=\"button\" variant=\"dark\" tone=\"text\" label=\"Anteprima\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Use Unsupported `tone` Values\n\n`<mds-button-dropdown>` accepts `ToneMinimalVariantType`, which is `strong` and `weak` only. Passing `outline`, `text`, or `box` is not valid for this component: the value reaches the internal buttons unchecked, without the split-button styling that only `strong` and `weak` have.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown label=\"Azione\" variant=\"primary\" tone=\"outline\"></mds-button-dropdown>\n<mds-button-dropdown label=\"Azione\" variant=\"primary\" tone=\"text\"></mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown label=\"Azione\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione\"></mds-button>\n</mds-button-dropdown>\n<mds-button-dropdown label=\"Azione\" variant=\"primary\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Opzione\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Try to Customize the Chevron Icon\n\nThe chevron trigger icon is internal and fixed. There is no prop to change it. Do not attempt to override it with CSS property hacks or shadow-DOM selectors.\n\n```css\n/* INCORRECT */\nmds-button-dropdown .dropdown-action mds-icon {\n content: url('custom-arrow.svg');\n}\n\n/* CORRECT - style only through documented custom properties and the dropdown part */\nmds-button-dropdown {\n --mds-button-dropdown-radius: var(--magma-radius-md);\n}\nmds-button-dropdown::part(dropdown) {\n box-shadow: var(--shadow-lg);\n}\n```\n\n#### Do Not Set Boolean Attributes to `\"false\"`\n\n`await`, `disabled`, and `active` are boolean attributes and `mds-button-dropdown` is form-associated: as on a native control, any value turns them on, `\"false\"` included, so this markup renders a disabled button that is waiting. Remove the attribute to turn it off.\n\n```html\n<!-- INCORRECT -->\n<mds-button-dropdown label=\"Invia\" await=\"false\" disabled=\"false\" variant=\"primary\"></mds-button-dropdown>\n\n<!-- CORRECT -->\n<mds-button-dropdown label=\"Invia\" variant=\"primary\" tone=\"strong\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Invia come bozza\"></mds-button>\n</mds-button-dropdown>\n```\n"
|
|
5362
5508
|
},
|
|
5363
5509
|
"props": [
|
|
@@ -6060,8 +6206,8 @@
|
|
|
6060
6206
|
}
|
|
6061
6207
|
],
|
|
6062
6208
|
"usage": {
|
|
6063
|
-
"1. Description": "The `<mds-button-group>` web component is a layout container of the Magma Design System that clusters related `<mds-button>` controls into a single, evenly-spaced horizontal group such as toolbars, action bars, or segmented sets of actions. It is a presentation-only wrapper with no props, events, or state - its sole job is to arrange its slotted children consistently.\n\n#### Semantic Behavior\n\n- **Default slot is content**: Whatever buttons (or button-like controls) you place inside are projected in source order. The group joins its `<mds-button>` / `<mds-button-dropdown>` members: it flattens their inner corners and sets them 2px apart, so only the outer corners of the cluster stay rounded.\n- **Inline layout**: The group shrinks to fit its content with consistent spacing and stays inline with surrounding elements
|
|
6064
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-button-group>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Toolbar of Icon-Only Actions\n\nThe primary use case. Group icon-only `<mds-button>` elements that act on the same target - a text selection, a table row, or an editor surface. Each button must carry an explicit `aria-label` because no visible label is present.\n\n```html\n<mds-button-group>\n <mds-button icon=\"mi/baseline/format-bold\" aria-label=\"Grassetto\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-italic\" aria-label=\"Corsivo\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-underlined\" aria-label=\"Sottolineato\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-button-group>\n```\n\n#### Segmented Set of Labelled Actions\n\nUse labelled buttons when the actions benefit from visible text - for example a primary / secondary / destructive trio at the bottom of a form section.\n\n```html\n<mds-button-group>\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n</mds-button-group>\n```\n\n#### Mixed Emphasis Within a Group\n\nPair a high-emphasis primary button with lower-emphasis supporting actions. Keep the same `variant` family and vary only the `tone` so the group reads as a cohesive cluster, not a random set of buttons.\n\n```html\n<mds-button-group>\n <mds-button label=\"Pubblica\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button label=\"Salva come bozza\" variant=\"primary\" tone=\"outline\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-button-group>\n```\n\n#### Inside a Toolbar or Action Bar\n\n`<mds-button-group>` is `inline-flex` by default, so multiple groups sit naturally beside other inline controls in a toolbar without extra CSS.\n\n```html\n<div class=\"toolbar\">\n <mds-button-group>\n <mds-button icon=\"mi/baseline/undo\" aria-label=\"Annulla\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/redo\" aria-label=\"Ripristina\" variant=\"dark\" tone=\"text\"></mds-button>\n </mds-button-group>\n\n <mds-button-group>\n <mds-button icon=\"mi/baseline/format-bold\" aria-label=\"Grassetto\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-italic\" aria-label=\"Corsivo\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-underlined\" aria-label=\"Sottolineato\" variant=\"dark\" tone=\"text\"></mds-button>\n </mds-button-group>\n</div>\n```\n\n#### Including a `<mds-button-dropdown>` in the Group\n\nThe default slot accepts any `<mds-button>` or `<mds-button-dropdown>` sibling component. Place the dropdown last or first depending on visual priority.\n\n```html\n<mds-button-group>\n <mds-button label=\"Esporta CSV\" variant=\"primary\" tone=\"weak\"></mds-button>\n <mds-button-dropdown label=\"Altre opzioni\" variant=\"primary\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Esporta PDF\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Esporta Excel\"></mds-button>\n </mds-button-dropdown>\n</mds-button-group>\n```\n\n#### Disabled Buttons Inside a Group\n\nDisable individual buttons with the `disabled` boolean attribute. Never use `disabled=\"false\"` - remove the attribute to re-enable. The group itself has no `disabled` prop.\n\n```html\n<mds-button-group>\n <mds-button label=\"Approva\" variant=\"success\" tone=\"strong\"></mds-button>\n <mds-button label=\"Rifiuta\" variant=\"error\" tone=\"outline\" disabled></mds-button>\n</mds-button-group>\n```\n",
|
|
6209
|
+
"1. Description": "The `<mds-button-group>` web component is a layout container of the Magma Design System that clusters related `<mds-button>` controls into a single, evenly-spaced horizontal group such as toolbars, action bars, or segmented sets of actions. It is a presentation-only wrapper with no props, events, or state - its sole job is to arrange its slotted children consistently.\n\n#### Semantic Behavior\n\n- **Default slot is content**: Whatever buttons (or button-like controls) you place inside are projected in source order. The group joins its `<mds-button>` / `<mds-button-dropdown>` members: it flattens their inner corners and sets them 2px apart, so only the outer corners of the cluster stay rounded.\n- **Inline layout**: The group shrinks to fit its content with consistent spacing and stays inline with surrounding elements; on its own it never takes the full row width.\n- **Width in a stretched row**: A row that stretches the group, as `actions/stacked` does under `--magma-container-actions` (380px) in `<mds-card-footer>`, `<mds-banner>`, `<mds-status-bar>` or a row of your own (`align-self: stretch`, a `width`, a `flex-basis`), gets the cluster across the whole row, as every other labelled action of it: each labelled member keeps its own width plus the same share of the free width, its label in the middle, so a long label is never cut for a short one; an `<mds-button-dropdown>` member gives its share to its primary action, and an icon-only member keeps its size.\n- **No own semantics**: It exposes no role, ARIA attributes, form association, focus management, or keyboard handling of its own - accessibility and interaction live entirely in the slotted children. It is purely a visual grouping primitive.\n\n#### Properties & Visual Configurations\n\nThis component has no configurable properties. Visual outcome is determined entirely by the slotted children - typically a set of `<mds-button>` elements sharing a common `variant` / `tone` (see the shared ladder in [`agents/variants.md`](../../../../agents/variants.md)) so the group reads as a cohesive cluster of actions.\n",
|
|
6210
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-button-group>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Toolbar of Icon-Only Actions\n\nThe primary use case. Group icon-only `<mds-button>` elements that act on the same target - a text selection, a table row, or an editor surface. Each button must carry an explicit `aria-label` because no visible label is present.\n\n```html\n<mds-button-group>\n <mds-button icon=\"mi/baseline/format-bold\" aria-label=\"Grassetto\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-italic\" aria-label=\"Corsivo\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-underlined\" aria-label=\"Sottolineato\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-button-group>\n```\n\n#### Segmented Set of Labelled Actions\n\nUse labelled buttons when the actions benefit from visible text - for example a primary / secondary / destructive trio at the bottom of a form section.\n\n```html\n<mds-button-group>\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n</mds-button-group>\n```\n\n#### Mixed Emphasis Within a Group\n\nPair a high-emphasis primary button with lower-emphasis supporting actions. Keep the same `variant` family and vary only the `tone` so the group reads as a cohesive cluster, not a random set of buttons.\n\n```html\n<mds-button-group>\n <mds-button label=\"Pubblica\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button label=\"Salva come bozza\" variant=\"primary\" tone=\"outline\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-button-group>\n```\n\n#### Inside a Toolbar or Action Bar\n\n`<mds-button-group>` is `inline-flex` by default, so multiple groups sit naturally beside other inline controls in a toolbar without extra CSS.\n\n```html\n<div class=\"toolbar\">\n <mds-button-group>\n <mds-button icon=\"mi/baseline/undo\" aria-label=\"Annulla\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/redo\" aria-label=\"Ripristina\" variant=\"dark\" tone=\"text\"></mds-button>\n </mds-button-group>\n\n <mds-button-group>\n <mds-button icon=\"mi/baseline/format-bold\" aria-label=\"Grassetto\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-italic\" aria-label=\"Corsivo\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/format-underlined\" aria-label=\"Sottolineato\" variant=\"dark\" tone=\"text\"></mds-button>\n </mds-button-group>\n</div>\n```\n\n#### Including a `<mds-button-dropdown>` in the Group\n\nThe default slot accepts any `<mds-button>` or `<mds-button-dropdown>` sibling component. Place the dropdown last or first depending on visual priority.\n\n```html\n<mds-button-group>\n <mds-button label=\"Esporta CSV\" variant=\"primary\" tone=\"weak\"></mds-button>\n <mds-button-dropdown label=\"Altre opzioni\" variant=\"primary\" tone=\"weak\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Esporta PDF\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Esporta Excel\"></mds-button>\n </mds-button-dropdown>\n</mds-button-group>\n```\n\n#### In a Row of Actions That Stacks\n\nStretch the group as any other action of the row: under `--magma-container-actions` of its container (`@max-actions:`), `actions/stacked` puts every labelled action at the full width, and the group shares that width among its labelled members, the joined corners as before. No part or custom property is needed.\n\n```html\n<div class=\"@container\">\n <div class=\"flex justify-end gap-inline @max-actions:flex-col @max-actions:*:self-stretch\">\n <mds-button variant=\"dark\" tone=\"outline\" label=\"Annulla\"></mds-button>\n <mds-button-group>\n <mds-button variant=\"primary\" tone=\"outline\" label=\"Salva come bozza\"></mds-button>\n <mds-button variant=\"primary\" label=\"Pubblica\"></mds-button>\n </mds-button-group>\n </div>\n</div>\n```\n\n#### Disabled Buttons Inside a Group\n\nDisable individual buttons with the `disabled` boolean attribute. Never use `disabled=\"false\"` - remove the attribute to re-enable. The group itself has no `disabled` prop.\n\n```html\n<mds-button-group>\n <mds-button label=\"Approva\" variant=\"success\" tone=\"strong\"></mds-button>\n <mds-button label=\"Rifiuta\" variant=\"error\" tone=\"outline\" disabled></mds-button>\n</mds-button-group>\n```\n",
|
|
6065
6211
|
"3. Mistakes": "Common incorrect uses of `<mds-button-group>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Nest Raw `<button>` Elements Inside the Group\n\nThe group is part of the Magma component system and is designed to host `<mds-button>` (and sibling `mds-*` action) components. Raw `<button>` elements bypass theming, focus styles, and accessibility defaults.\n\n```html\n<!-- INCORRECT -->\n<mds-button-group>\n <button class=\"btn\">Salva</button>\n <button class=\"btn\">Annulla</button>\n</mds-button-group>\n\n<!-- CORRECT -->\n<mds-button-group>\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n</mds-button-group>\n```\n\n#### Do Not Wrap the Group in an Anchor\n\n`<mds-button-group>` contains interactive controls; nesting the whole group inside `<a>` creates nested interactives, breaks keyboard semantics, and fails accessibility audits. Use the `href` prop on individual `<mds-button>` elements instead.\n\n```html\n<!-- INCORRECT -->\n<a href=\"/azioni\">\n <mds-button-group>\n <mds-button label=\"Vai\" variant=\"primary\"></mds-button>\n </mds-button-group>\n</a>\n\n<!-- CORRECT -->\n<mds-button-group>\n <mds-button label=\"Vai\" href=\"/azioni\" variant=\"primary\"></mds-button>\n</mds-button-group>\n```\n\n#### Do Not Omit `aria-label` on Icon-Only Buttons Inside a Group\n\nGrouping icon-only buttons does not remove the requirement for an accessible name on each child. Without it `mds-button` falls back to the last segment of the icon slug (\"undo\"), which names the icon, not the action.\n\n```html\n<!-- INCORRECT -->\n<mds-button-group>\n <mds-button icon=\"mi/baseline/undo\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/redo\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-button-group>\n\n<!-- CORRECT -->\n<mds-button-group>\n <mds-button icon=\"mi/baseline/undo\" aria-label=\"Annulla\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button icon=\"mi/baseline/redo\" aria-label=\"Ripristina\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-button-group>\n```\n\n#### Do Not Nest `<mds-button-group>` Inside Another Group\n\nThe component is a flat layout primitive; nesting groups creates redundant flex containers that break the consistent spacing and group visual coherence. Keep the hierarchy flat.\n\n```html\n<!-- INCORRECT -->\n<mds-button-group>\n <mds-button-group>\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button label=\"Bozza\" variant=\"primary\" tone=\"outline\"></mds-button>\n </mds-button-group>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-button-group>\n\n<!-- CORRECT -->\n<mds-button-group>\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button label=\"Bozza\" variant=\"primary\" tone=\"outline\"></mds-button>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-button-group>\n```\n\n#### Do Not Override Spacing with Inline Styles\n\nThe component manages its own gap via a design-token-backed CSS value. Setting inline `gap`, `margin`, or `padding` on the host or child buttons breaks the token contract and may produce inconsistent spacing across themes.\n\n```css\n/* INCORRECT */\nmds-button-group {\n gap: 16px;\n}\nmds-button-group mds-button {\n margin-right: 8px;\n}\n\n/* CORRECT - let the component handle spacing; style only what it exposes */\nmds-button-group {\n /* no gap or margin overrides needed */\n}\n```\n"
|
|
6066
6212
|
},
|
|
6067
6213
|
"props": [],
|
|
@@ -6099,11 +6245,49 @@
|
|
|
6099
6245
|
}
|
|
6100
6246
|
],
|
|
6101
6247
|
"usage": {
|
|
6102
|
-
"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- **
|
|
6103
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-calendar>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Single-Day Picker\n\nSet the bare `single-picker` attribute for a plain single-date selector. `mdsCalendarChange` fires once with `{ startDate }` and no `endDate`. Seed an initial date via `start-date`.\n\n```html\n<mds-calendar single-picker start-date=\"2025-06-10\"></mds-calendar>\n\n<script>\n document.querySelector('mds-calendar').addEventListener('mdsCalendarChange', (e) => {\n console.log('Data selezionata:', e.detail.startDate);\n });\n</script>\n```\n\n#### Range Picker (default mode)\n\nRange selection is the default: omit `single-picker`. The first click sets the start date, the second sets the end date. A
|
|
6104
|
-
"3. Mistakes": "Common incorrect uses of `<mds-calendar>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Toggle Single Mode with a Quoted Boolean String\n\n`singlePicker` is a boolean prop that defaults to `false`. The component reads the string `\"false\"` as `false`, but the prop is not reflected, so `single-picker=\"false\"` stays in the DOM and attribute selectors (`mds-calendar[single-picker]`) and any code reading the attribute still see it set. Use the bare attribute for single mode and omit it for the default range mode; toggle it at runtime by adding/removing the attribute or setting the property in JavaScript.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar single-picker=\"false\"></mds-calendar>\n\n<!-- CORRECT -->\n<mds-calendar></mds-calendar>\n<mds-calendar id=\"cal\" single-picker></mds-calendar>\n<script>\n document.querySelector('#cal').singlePicker = false; // back to range mode\n</script>\n```\n\n#### Do Not Set `end-date` When `single-picker` Is Set\n\nWhen `singlePicker` is set, the component rejects `endDate` with a console warning and clears it internally. Setting both `single-picker` and `end-date` is contradictory and produces no visible selection for the end date.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar single-picker start-date=\"2025-06-01\" end-date=\"2025-06-15\"></mds-calendar>\n\n<!-- CORRECT -->\n<mds-calendar single-picker start-date=\"2025-06-01\"></mds-calendar>\n```\n\n#### Do Not Provide `startDate` After `endDate`\n\nDates must be chronologically ordered: `startDate` must precede `endDate`. The component
|
|
6248
|
+
"1. Description": "The `<mds-calendar>` web component is the date-selection surface of the Magma Design System: a localized month grid that lets users pick either a single day or a date range. It is the visual engine behind `mds-input-date` and `mds-input-date-range`.\n\n#### Semantic Behavior\n\n- **Range vs. single mode**: range selection is the default; set `singlePicker` to pick one day. In range mode the first click sets the start, the second sets the end, and a third click starts a new range from the clicked day; in single mode each click replaces the prior choice.\n- **Active end**: a parent that lets the user choose which end to change, as [`mds-input-date-range`](../mds-input-date-range/AGENTS.md) does, names it in `activeEnd` (`start` or `end`): a click then changes that end only, also on a complete range, instead of starting a new one. With no start, a click picks the start whatever `activeEnd` says.\n- **Never backwards**: a click never swaps the ends. A day before the start, clicked while the end is picked, becomes the new start and the end is still to pick; a day after the end, clicked while the start is picked (`activeEnd=\"start\"`), becomes the new start and the end is emptied. A `startDate` / `endDate` pair given backwards, in the markup or from code, is put in order (with a console warning); a parent that sets the two props one after the other is read once both have arrived, so a start moved past the old end is not taken for a range given backwards.\n- **Hover preview**: While a range waits for its end, the day under the pointer is previewed: the band from the start to that day when a click there would end the range, that day alone when it would become a new start. The preview is dropped with the click that changes the range.\n- **Marks**: a chosen day, either end of a range or the day of a single picker, is a full dot, the start and the end alike, and the days between them a band; the day under the pointer, not chosen yet, is a ring on a paler band.\n- **Min/max bounds**: `min` and `max` mark out-of-range day cells as disabled, blocking their selection.\n- **Multi-view navigation**: The header toggles between the day grid, a month picker, and a year picker; the year view pages in decades while the calendar view pages month by month. The two arrows are icon-only buttons named in the page language (the `lang` of `<html>`): previous / next month on the day grid, previous / next years in the year view; the month picker has nothing to page through, so there they are disabled. The header is a navigation landmark named after the month and year it shows, so two calendars side by side are two distinct landmarks.\n- **Localization**: Weekday names, month names, and cell titles are formatted in the page language (the `lang` attribute of `<html>`, `en` when absent).\n- **Emitted events**: `mdsCalendarChange` fires on every pick with `{ startDate, endDate? }`: in range mode the first click emits `{ startDate }` alone, the second the full range; `mdsCalendarPreselect` fires only with a completed range, to let preselection shortcuts re-evaluate their state.\n- **Preselection slot**: A `preselection` named slot hosts quick-pick shortcuts. The area appears while the slot holds an element, one added after load included; `hidePreselection` collapses it. The `date-preselection--has-preselection` class earlier versions required is no longer needed (it still shows the area).\n\n#### Properties & Visual Configurations\n\nDates are exchanged as ISO 8601 strings (`YYYY-MM-DD`). `startDate` and `endDate` seed the selection (a click updates the internal selection and emits `mdsCalendarChange`, it does not rewrite the attributes); on load, a valid `startDate` also determines which month is shown first.\n\n- **`singlePicker`** is the mode switch: omit it for two-ended range selection, set it for single-day pickers. When set, any `endDate` is ignored and cleared with a warning.\n- **`activeEnd`** names the end the next click picks, for a parent that shows the user which one it is; leave it unset on a calendar standing alone.\n- **`hidePreviousButton`** / **`hideNextButton`** remove one of the header navigation buttons, typically on calendars paired side by side; **`disableMonthYearSelection`** keeps the header on the day grid; **`hideToday`** removes the highlight on today's date.\n- Every boolean prop defaults to `false`: the feature is on until the bare attribute turns it off.\n- **`min`** / **`max`** define the selectable window; days outside it render disabled rather than being hidden.\n\nThis component does not use the shared `variant` / `tone` ladders on its host - those are defined in [`agents/variants.md`](../../../../agents/variants.md) and are applied internally to the navigation buttons it renders.\n",
|
|
6249
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-calendar>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Single-Day Picker\n\nSet the bare `single-picker` attribute for a plain single-date selector. `mdsCalendarChange` fires once with `{ startDate }` and no `endDate`. Seed an initial date via `start-date`.\n\n```html\n<mds-calendar single-picker start-date=\"2025-06-10\"></mds-calendar>\n\n<script>\n document.querySelector('mds-calendar').addEventListener('mdsCalendarChange', (e) => {\n console.log('Data selezionata:', e.detail.startDate);\n });\n</script>\n```\n\n#### Range Picker (default mode)\n\nRange selection is the default: omit `single-picker`. The first click sets the start date, the second sets the end date; a second click before the start makes that day the new start, and the end is still to pick. A click on a complete range starts a new range from the clicked day. `mdsCalendarChange` fires on every click: while the end is missing `endDate` is absent. Preload a range by supplying both `start-date` and `end-date`.\n\n```html\n<mds-calendar start-date=\"2025-09-01\" end-date=\"2025-09-15\"></mds-calendar>\n\n<script>\n document.querySelector('mds-calendar').addEventListener('mdsCalendarChange', (e) => {\n const { startDate, endDate } = e.detail;\n console.log('Intervallo selezionato:', startDate, '-', endDate);\n });\n</script>\n```\n\n#### Naming the End a Click Picks\n\nA parent that lets the user choose which end to change sets `active-end` to `start` or `end`, and keeps it in step with what the user picks: a click then changes that end only, also on a complete range. A click never puts the range backwards: picking the end, a day before the start becomes the new start; picking the start, a day after the end becomes the new start and empties the end. [`mds-input-date-range`](../mds-input-date-range/AGENTS.md) drives its calendars this way from its fields and from the header of its panel; prefer it to a calendar of your own.\n\n```html\n<mds-calendar id=\"periodo\" start-date=\"2025-09-01\" end-date=\"2025-09-15\" active-end=\"start\"></mds-calendar>\n\n<script>\n const calendar = document.querySelector('#periodo');\n calendar.addEventListener('mdsCalendarChange', () => {\n // the start is picked: the end comes next\n calendar.activeEnd = 'end';\n });\n</script>\n```\n\n#### Restricting the Selectable Window with `min` / `max`\n\nPass ISO 8601 strings to `min` and `max` to mark out-of-range days as disabled. Days outside the window are not hidden - they remain visible but cannot be clicked.\n\n```html\n<mds-calendar\n single-picker\n min=\"2025-01-01\"\n max=\"2025-12-31\"\n></mds-calendar>\n```\n\n#### Navigating to a Specific Month Programmatically\n\nUse the `updateCurrentDate` method to jump the visible month without changing the current selection. Pass any ISO date string that falls within the target month.\n\n```html\n<mds-calendar id=\"cal\" single-picker></mds-calendar>\n\n<script>\n document.querySelector('#cal').updateCurrentDate('2026-03-01');\n</script>\n```\n\n#### Quick-Pick Preselection Shortcuts\n\nThe `preselection` named slot hosts your own shortcuts, for example `mds-button` elements whose `click` sets `start-date` / `end-date` ([`mds-input-date-range-preselection`](../mds-input-date-range-preselection/AGENTS.md) works only inside `mds-input-date-range`). The slot panel becomes visible as soon as the slot holds an element, also one added after load; set `hide-preselection` to keep it collapsed. `mdsCalendarPreselect` fires after each completed range selection so the shortcuts can re-evaluate their active state.\n\n```html\n<mds-calendar start-date=\"2025-09-01\" end-date=\"2025-09-07\">\n <div slot=\"preselection\">\n <mds-button variant=\"dark\" tone=\"text\" label=\"Ultimi 7 giorni\"></mds-button>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Ultimi 30 giorni\"></mds-button>\n </div>\n</mds-calendar>\n```\n\n#### Paired Calendars Without Duplicate Navigation\n\nTwo calendars shown side by side (the pattern used by `mds-input-date-range` on wide viewports) should expose one previous and one next button in total: hide the inner buttons with `hide-previous-button` / `hide-next-button` and lock the header on the day grid with `disable-month-year-selection`, then keep the two `view-date` values one month apart from the `mdsCalendarNavigate` event.\n\n```html\n<mds-calendar id=\"start\" view-date=\"2025-09-01\" hide-next-button disable-month-year-selection></mds-calendar>\n<mds-calendar id=\"end\" view-date=\"2025-10-01\" hide-previous-button disable-month-year-selection></mds-calendar>\n```\n\n#### Listening for Selection Changes\n\nListen on the documented `mdsCalendarChange` event - not the native `change` event - so the handler receives the structured `{ startDate, endDate? }` detail object directly from the Shadow DOM.\n\n```html\n<mds-calendar id=\"picker\" single-picker></mds-calendar>\n\n<script>\n document.querySelector('#picker').addEventListener('mdsCalendarChange', (e) => {\n const { startDate } = e.detail;\n document.querySelector('#output').textContent = 'Scadenza: ' + startDate;\n });\n</script>\n```\n\n#### Embedded inside `mds-input-date` or `mds-input-date-range`\n\n`<mds-calendar>` is the visual engine used internally by [`mds-input-date`](../mds-input-date/AGENTS.md) and [`mds-input-date-range`](../mds-input-date-range/AGENTS.md). In most product surfaces, reach for those higher-level components. Use `<mds-calendar>` directly only when you need a standalone always-visible date grid without an associated text input.\n\n```html\n<!-- Higher-level: input with calendar overlay -->\n<mds-input-field label=\"Scadenza\">\n <mds-input-date name=\"scadenza\"></mds-input-date>\n</mds-input-field>\n\n<!-- Lower-level: always-visible standalone grid -->\n<mds-calendar single-picker></mds-calendar>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nAdjust the calendar appearance only through the public `--mds-calendar-*` CSS custom properties. Set them on the host element or a parent selector; use the semantic color roles so dark mode, named themes and high contrast keep working. The day cells inherit from the calendar their own public `--mds-calendar-cell-*` properties, documented on [`mds-calendar-cell`](../mds-calendar-cell/AGENTS.md).\n\n```css\n.booking-widget mds-calendar {\n --mds-calendar-background: rgb(var(--magma-surface-muted));\n --mds-calendar-border-radius: var(--magma-radius-xl);\n --mds-calendar-padding: calc(var(--spacing) * 500);\n --mds-calendar-cell-other-month-visibility: hidden;\n}\n```\n",
|
|
6250
|
+
"3. Mistakes": "Common incorrect uses of `<mds-calendar>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Toggle Single Mode with a Quoted Boolean String\n\n`singlePicker` is a boolean prop that defaults to `false`. The component reads the string `\"false\"` as `false`, but the prop is not reflected, so `single-picker=\"false\"` stays in the DOM and attribute selectors (`mds-calendar[single-picker]`) and any code reading the attribute still see it set. Use the bare attribute for single mode and omit it for the default range mode; toggle it at runtime by adding/removing the attribute or setting the property in JavaScript.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar single-picker=\"false\"></mds-calendar>\n\n<!-- CORRECT -->\n<mds-calendar></mds-calendar>\n<mds-calendar id=\"cal\" single-picker></mds-calendar>\n<script>\n document.querySelector('#cal').singlePicker = false; // back to range mode\n</script>\n```\n\n#### Do Not Set `end-date` When `single-picker` Is Set\n\nWhen `singlePicker` is set, the component rejects `endDate` with a console warning and clears it internally. Setting both `single-picker` and `end-date` is contradictory and produces no visible selection for the end date.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar single-picker start-date=\"2025-06-01\" end-date=\"2025-06-15\"></mds-calendar>\n\n<!-- CORRECT -->\n<mds-calendar single-picker start-date=\"2025-06-01\"></mds-calendar>\n```\n\n#### Do Not Provide `startDate` After `endDate`\n\nDates must be chronologically ordered: `startDate` must precede `endDate`. The component puts a pair given backwards in order, with a console warning, but the warning is noise in the console of the page and the swap may not be the range the user meant. Always ensure `start-date <= end-date`; setting the two one after the other in the same task is fine, the calendar reads them once both have arrived.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar start-date=\"2025-12-31\" end-date=\"2025-12-01\"></mds-calendar>\n\n<!-- CORRECT -->\n<mds-calendar start-date=\"2025-12-01\" end-date=\"2025-12-31\"></mds-calendar>\n```\n\n#### Do Not Listen for the Native `change` Event\n\n`<mds-calendar>` does not bubble a native `change` event from inside its Shadow DOM. Use the documented `mdsCalendarChange` custom event so the handler reliably receives the structured `{ startDate, endDate? }` payload.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar id=\"cal\"></mds-calendar>\n<script>\n document.querySelector('#cal').addEventListener('change', (e) => {\n console.log(e.target.value); // undefined - wrong event\n });\n</script>\n\n<!-- CORRECT -->\n<mds-calendar id=\"cal\"></mds-calendar>\n<script>\n document.querySelector('#cal').addEventListener('mdsCalendarChange', (e) => {\n console.log(e.detail.startDate, e.detail.endDate);\n });\n</script>\n```\n\n#### Do Not Use `<mds-calendar>` as a Drop-In Replacement for `mds-input-date`\n\n`<mds-calendar>` is not form-associated and emits no `name`/`value` pair for form submission. When you need a date picker tied to a form field, use [`mds-input-date`](../mds-input-date/AGENTS.md) (single date) or [`mds-input-date-range`](../mds-input-date-range/AGENTS.md) (range) instead.\n\n```html\n<!-- INCORRECT -->\n<form action=\"/prenota\" method=\"post\">\n <mds-calendar name=\"check-in\" single-picker></mds-calendar>\n <mds-button type=\"submit\" label=\"Prenota\"></mds-button>\n</form>\n\n<!-- CORRECT -->\n<form action=\"/prenota\" method=\"post\">\n <mds-input-field label=\"Data di arrivo\">\n <mds-input-date name=\"check-in\"></mds-input-date>\n </mds-input-field>\n <mds-button type=\"submit\" label=\"Prenota\"></mds-button>\n</form>\n```\n\n#### Do Not Style Internals via Undocumented `::part()` Selectors\n\nThe only supported customization surface is the set of public `--mds-calendar-*` CSS custom properties. Targeting shadow-DOM internals with `::part()` selectors that are not in the documentation couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-calendar::part(nav) {\n background: red;\n}\nmds-calendar::part(cell) {\n border: 1px solid blue;\n}\n\n/* CORRECT */\nmds-calendar {\n --mds-calendar-background: rgb(var(--magma-surface-muted));\n --mds-calendar-border-radius: var(--magma-radius-xl);\n --mds-calendar-cell-other-month-visibility: hidden;\n}\n```\n"
|
|
6105
6251
|
},
|
|
6106
6252
|
"props": [
|
|
6253
|
+
{
|
|
6254
|
+
"name": "activeEnd",
|
|
6255
|
+
"type": "\"end\" | \"start\" | undefined",
|
|
6256
|
+
"complexType": {
|
|
6257
|
+
"original": "CalendarRangeEndType",
|
|
6258
|
+
"resolved": "\"end\" | \"start\" | undefined",
|
|
6259
|
+
"references": {
|
|
6260
|
+
"CalendarRangeEndType": {
|
|
6261
|
+
"location": "import",
|
|
6262
|
+
"path": "./meta/types",
|
|
6263
|
+
"id": "src/components/mds-calendar/meta/types.ts::CalendarRangeEndType",
|
|
6264
|
+
"referenceLocation": "CalendarRangeEndType"
|
|
6265
|
+
}
|
|
6266
|
+
}
|
|
6267
|
+
},
|
|
6268
|
+
"mutable": false,
|
|
6269
|
+
"attr": "active-end",
|
|
6270
|
+
"reflectToAttr": true,
|
|
6271
|
+
"docs": "Specifies the end of the range the next click picks, `start` or `end`, for a parent that\nlets the user choose it, as `mds-input-date-range` does from its fields and from the header\nof its panel. A click never puts the range backwards: a day after the end, picked as the\nstart, becomes the new start and empties the end; a day before the start, picked as the end,\nbecomes the new start and leaves the end to pick. With no start, a click picks the start.\nLeft unset, the calendar picks the start, then the end, and a click on a complete range\nstarts a new one.",
|
|
6272
|
+
"docsTags": [],
|
|
6273
|
+
"values": [
|
|
6274
|
+
{
|
|
6275
|
+
"value": "end",
|
|
6276
|
+
"type": "string"
|
|
6277
|
+
},
|
|
6278
|
+
{
|
|
6279
|
+
"value": "start",
|
|
6280
|
+
"type": "string"
|
|
6281
|
+
},
|
|
6282
|
+
{
|
|
6283
|
+
"type": "undefined"
|
|
6284
|
+
}
|
|
6285
|
+
],
|
|
6286
|
+
"optional": true,
|
|
6287
|
+
"required": false,
|
|
6288
|
+
"getter": false,
|
|
6289
|
+
"setter": false
|
|
6290
|
+
},
|
|
6107
6291
|
{
|
|
6108
6292
|
"name": "disableMonthYearSelection",
|
|
6109
6293
|
"type": "boolean",
|
|
@@ -6726,8 +6910,8 @@
|
|
|
6726
6910
|
}
|
|
6727
6911
|
],
|
|
6728
6912
|
"usage": {
|
|
6729
|
-
"1. Description": "The `<mds-calendar-cell>` web component represents a single selectable day inside the [`<mds-calendar>`](../mds-calendar/AGENTS.md) grid. It is a presentational child that renders the day number and exposes attributes the parent calendar drives to express the day's role and its position within a selection range.\n\n#### Semantic Behavior\n\n- **Compound child only**: It is rendered only by `<mds-calendar>`, which generates one cell per day of the visible month grid inside its own shadow DOM (the calendar has no default slot): consumers never write it, neither standalone nor as a child of the calendar.\n- **Parent-driven selection**: The cell holds no internal selection state. The parent calendar drives the `date`, `selection` and `preview` attributes to paint range boundaries and intermediate days; the cell only reflects what it is given.\n- **No own events**: Clicks and hover are handled by the parent (range building, preview, and the `mdsCalendarChange` / `mdsCalendarPreselect` events from `<mds-calendar>`). The cell itself emits nothing.\n- **Disabled state**: When `disabled` is set the day cannot be activated; the parent applies this for days outside the calendar's `min`/`max` range.\n- **Today marker**: `today` is a presentational flag the parent sets on the cell matching the current date, used only for styling emphasis.\n\n#### Properties & Visual Configurations\n\nMost props are state mirrors written by the parent rather than knobs a consumer tunes directly.\n\n- **`month`**: Distinguishes how the day relates to the displayed month - `current` for in-month days, `other` for leading/trailing days spilling in from adjacent months. The type also allows `weekend`, which is deprecated: the calendar never sets it and it has no styling of its own, since the weekend color comes from the cell's position (the last two columns of the week).\n- **`selection`**: Marks the cell's position within an active range - `start`, `end`, `middle`, or `single` (a one-day
|
|
6730
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-calendar-cell>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n`<mds-calendar-cell>` is an internal subpart: its real parent [`<mds-calendar>`](../mds-calendar/AGENTS.md) renders one cell per day inside its own shadow DOM and has no default slot, so cells written as its children are never shown. Every pattern below shows the `<mds-calendar>` markup that puts the cells in each state.\n\n#### Basic Cell Inside a Calendar\n\nThe typical form - let the parent render the cells and drive all their attributes (`date` in ISO `YYYY-MM-DD` format, `label`, `month`, `selection`, ...).\n\n```html\n<mds-calendar start-date=\"2024-06-01\" end-date=\"2024-06-15\"></mds-calendar>\n```\n\n#### Today Marker\n\nThe parent sets the `today` boolean attribute on the cell that matches the current date, which applies the accent-tinted styling that distinguishes today from other days. Set `hide-today` on the calendar to drop it.\n\n```html\n<mds-calendar></mds-calendar>\n<mds-calendar hide-today></mds-calendar>\n```\n\n#### Selection Range - Start, Middle, and End Positions\n\nThe parent sets `selection` to express where a cell falls inside the active range. The `start` and `end` values
|
|
6913
|
+
"1. Description": "The `<mds-calendar-cell>` web component represents a single selectable day inside the [`<mds-calendar>`](../mds-calendar/AGENTS.md) grid. It is a presentational child that renders the day number and exposes attributes the parent calendar drives to express the day's role and its position within a selection range.\n\n#### Semantic Behavior\n\n- **Compound child only**: It is rendered only by `<mds-calendar>`, which generates one cell per day of the visible month grid inside its own shadow DOM (the calendar has no default slot): consumers never write it, neither standalone nor as a child of the calendar.\n- **Parent-driven selection**: The cell holds no internal selection state. The parent calendar drives the `date`, `selection` and `preview` attributes to paint range boundaries and intermediate days; the cell only reflects what it is given.\n- **No own events**: Clicks and hover are handled by the parent (range building, preview, and the `mdsCalendarChange` / `mdsCalendarPreselect` events from `<mds-calendar>`). The cell itself emits nothing.\n- **Disabled state**: When `disabled` is set the day cannot be activated; the parent applies this for days outside the calendar's `min`/`max` range.\n- **Today marker**: `today` is a presentational flag the parent sets on the cell matching the current date, used only for styling emphasis.\n\n#### Properties & Visual Configurations\n\nMost props are state mirrors written by the parent rather than knobs a consumer tunes directly.\n\n- **`month`**: Distinguishes how the day relates to the displayed month - `current` for in-month days, `other` for leading/trailing days spilling in from adjacent months. The type also allows `weekend`, which is deprecated: the calendar never sets it and it has no styling of its own, since the weekend color comes from the cell's position (the last two columns of the week).\n- **`selection`**: Marks the cell's position within an active range - `start`, `end`, `middle`, or `single` (a day alone: a one-day range, the start of a range waiting for its end, the day of a single picker); absence or `none` means unselected. A chosen `start`, `end` or `single` is a full dot, the same mark for both ends; `middle` and the halves of the ends that reach it are the band of the range.\n- **`preview`**: When `true`, the selection is a preview of the day under the pointer rather than a chosen one: a paler band, and the `end` (or a `single`) drawn as a ring, not chosen yet. The `start` of a preview is the day already chosen and keeps its full dot.\n- **`orientation`**: Selection-connector direction. The type allows `horizontal`, `vertical`, and `both`, but only `horizontal` is currently supported.\n- **`date`**: The cell's ISO `YYYY-MM-DD` date; the parent matches against it to compute selection state, so it is required for the cell to participate in range logic.\n",
|
|
6914
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-calendar-cell>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n`<mds-calendar-cell>` is an internal subpart: its real parent [`<mds-calendar>`](../mds-calendar/AGENTS.md) renders one cell per day inside its own shadow DOM and has no default slot, so cells written as its children are never shown. Every pattern below shows the `<mds-calendar>` markup that puts the cells in each state.\n\n#### Basic Cell Inside a Calendar\n\nThe typical form - let the parent render the cells and drive all their attributes (`date` in ISO `YYYY-MM-DD` format, `label`, `month`, `selection`, ...).\n\n```html\n<mds-calendar start-date=\"2024-06-01\" end-date=\"2024-06-15\"></mds-calendar>\n```\n\n#### Today Marker\n\nThe parent sets the `today` boolean attribute on the cell that matches the current date, which applies the accent-tinted styling that distinguishes today from other days. Set `hide-today` on the calendar to drop it.\n\n```html\n<mds-calendar></mds-calendar>\n<mds-calendar hide-today></mds-calendar>\n```\n\n#### Selection Range - Start, Middle, and End Positions\n\nThe parent sets `selection` to express where a cell falls inside the active range. The `start` and `end` values are full dots, the same mark, with the band rounded around them; `middle` fills the span between them; `single` is a full dot with no band.\n\n```html\n<!-- 3 June: start, 4 June: middle, 5 June: end -->\n<mds-calendar start-date=\"2024-06-03\" end-date=\"2024-06-05\"></mds-calendar>\n```\n\n#### Single-Day Selection\n\nThe parent uses `selection=\"single\"` for the day of a single picker, for a range whose two ends are the same day, and for the start of a range still waiting for its end. The day is a full dot, with no band, as it reaches no other day.\n\n```html\n<mds-calendar single-picker start-date=\"2024-06-10\"></mds-calendar>\n```\n\n#### Preview (Hover) Selection\n\nWhile the user hovers toward the end of a range, the parent sets `preview` on the cells from the start to the hovered day: the band is paler, the hovered day is a ring, and the start keeps the full dot of a chosen day. A hovered day that a click would make the new start, one before the start, is a `single` `preview` alone: a ring with no band.\n\n```html\n<!-- range mode with a start and no end: hovering a later day previews the range -->\n<mds-calendar start-date=\"2024-06-07\"></mds-calendar>\n```\n\n#### Days from Adjacent Months\n\nThe parent renders the leading and trailing days that fill the grid but belong to the previous or next month with `month=\"other\"`. Inside `<mds-calendar>` these cells are dimmed and visible; set `--mds-calendar-cell-other-month-visibility: hidden` on the calendar to hide them.\n\n```html\n<mds-calendar view-date=\"2024-06-01\" style=\"--mds-calendar-cell-other-month-visibility: hidden;\"></mds-calendar>\n```\n\n#### Disabled Day\n\nThe parent sets the `disabled` boolean attribute on days that cannot be selected - the dates outside its `min`/`max` range. A disabled cell removes pointer events and applies the disabled color automatically.\n\n```html\n<mds-calendar view-date=\"2024-06-01\" min=\"2024-06-10\"></mds-calendar>\n```\n\n#### Styling Customization\n\nThe cells live in the calendar's shadow DOM, so their public `--mds-calendar-cell-*` CSS custom properties reach them by inheritance: set them on the `<mds-calendar>` host (or on a parent selector), next to the public custom properties the calendar documents for them. The colors of the weekend, selected, preselected, disabled and adjacent-month days are not public: they follow the theme. Use the semantic color roles so dark mode, named themes and high contrast keep working.\n\n```css\n.booking-calendar mds-calendar {\n --mds-calendar-cell-other-month-visibility: hidden;\n --mds-calendar-cell-background: rgb(var(--magma-wash-soft));\n --mds-calendar-cell-color: rgb(var(--magma-text-muted));\n}\n```\n",
|
|
6731
6915
|
"3. Mistakes": "Common incorrect uses of `<mds-calendar-cell>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use the Cell Outside Its Parent Calendar\n\n`<mds-calendar-cell>` is rendered by [`<mds-calendar>`](../mds-calendar/AGENTS.md) itself, one per day inside its shadow DOM. Used in isolation it loses the gap context that drives range connector geometry and no parent coordinates selection across cells; slotted into `<mds-calendar>`, which has no default slot, it is never shown. Let the calendar generate the cells.\n\n```html\n<!-- INCORRECT -->\n<mds-calendar-cell date=\"2024-06-10\" label=\"10\" month=\"current\" selection=\"single\"></mds-calendar-cell>\n\n<!-- CORRECT -->\n<mds-calendar single-picker start-date=\"2024-06-10\"></mds-calendar>\n```\n\n#### Do Not Manage Selection State Locally in the Cell\n\nThe cell is purely presentational - it holds no internal state. Setting `selection` directly on isolated cells and keeping them in sync by hand duplicates the logic the parent calendar already owns and will diverge on re-renders.\n\n```html\n<!-- INCORRECT: manually wiring selection outside mds-calendar -->\n<div class=\"custom-grid\">\n <mds-calendar-cell date=\"2024-06-03\" label=\"3\" selection=\"start\"></mds-calendar-cell>\n <mds-calendar-cell date=\"2024-06-04\" label=\"4\" selection=\"middle\"></mds-calendar-cell>\n <mds-calendar-cell date=\"2024-06-05\" label=\"5\" selection=\"end\"></mds-calendar-cell>\n</div>\n\n<!-- CORRECT: let mds-calendar own range state and drive cell props -->\n<mds-calendar start-date=\"2024-06-03\" end-date=\"2024-06-05\"></mds-calendar>\n```\n\n#### Do Not Pierce the Shadow DOM to Style Internals\n\nThe cells live in the shadow DOM of `<mds-calendar>`: from outside they are adjusted only through their public `--mds-calendar-cell-*` custom properties, set on the calendar, which the cells inherit. Targeting the internal `.action`, `.inner-dot`, or `.area-background` elements via `>>>` or undocumented class selectors couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-calendar-cell >>> .area-background {\n background: hotpink;\n}\nmds-calendar-cell >>> .inner-dot {\n display: none;\n}\n\n/* CORRECT */\nmds-calendar {\n --mds-calendar-cell-other-month-visibility: hidden;\n --mds-calendar-cell-background: rgb(var(--magma-wash-soft));\n}\n```\n"
|
|
6732
6916
|
},
|
|
6733
6917
|
"props": [
|
|
@@ -7105,49 +7289,61 @@
|
|
|
7105
7289
|
{
|
|
7106
7290
|
"name": "--mds-calendar-cell-preselection-current-month-background",
|
|
7107
7291
|
"annotation": "prop",
|
|
7108
|
-
"docs": "Background
|
|
7292
|
+
"docs": "Background of the band of a preview, from the start to the day under the pointer (current month).",
|
|
7109
7293
|
"visibility": "internal"
|
|
7110
7294
|
},
|
|
7111
7295
|
{
|
|
7112
7296
|
"name": "--mds-calendar-cell-preselection-current-month-boundaries-background",
|
|
7113
7297
|
"annotation": "prop",
|
|
7114
|
-
"docs": "
|
|
7298
|
+
"docs": "Fill of the ring of the day under the pointer (current month).",
|
|
7299
|
+
"visibility": "internal"
|
|
7300
|
+
},
|
|
7301
|
+
{
|
|
7302
|
+
"name": "--mds-calendar-cell-preselection-current-month-boundaries-border-color",
|
|
7303
|
+
"annotation": "prop",
|
|
7304
|
+
"docs": "Ring of the day under the pointer, not chosen yet (current month).",
|
|
7115
7305
|
"visibility": "internal"
|
|
7116
7306
|
},
|
|
7117
7307
|
{
|
|
7118
7308
|
"name": "--mds-calendar-cell-preselection-current-month-boundaries-color",
|
|
7119
7309
|
"annotation": "prop",
|
|
7120
|
-
"docs": "
|
|
7310
|
+
"docs": "Text color of the day under the pointer, the end a click there would pick (current month).",
|
|
7121
7311
|
"visibility": "internal"
|
|
7122
7312
|
},
|
|
7123
7313
|
{
|
|
7124
7314
|
"name": "--mds-calendar-cell-preselection-current-month-color",
|
|
7125
7315
|
"annotation": "prop",
|
|
7126
|
-
"docs": "Text color
|
|
7316
|
+
"docs": "Text color of the band of a preview (current month).",
|
|
7127
7317
|
"visibility": "internal"
|
|
7128
7318
|
},
|
|
7129
7319
|
{
|
|
7130
7320
|
"name": "--mds-calendar-cell-preselection-other-month-background",
|
|
7131
7321
|
"annotation": "prop",
|
|
7132
|
-
"docs": "Background
|
|
7322
|
+
"docs": "Background of the band of a preview (other months).",
|
|
7133
7323
|
"visibility": "internal"
|
|
7134
7324
|
},
|
|
7135
7325
|
{
|
|
7136
7326
|
"name": "--mds-calendar-cell-preselection-other-month-boundaries-background",
|
|
7137
7327
|
"annotation": "prop",
|
|
7138
|
-
"docs": "
|
|
7328
|
+
"docs": "Fill of the ring of the day under the pointer (other months).",
|
|
7329
|
+
"visibility": "internal"
|
|
7330
|
+
},
|
|
7331
|
+
{
|
|
7332
|
+
"name": "--mds-calendar-cell-preselection-other-month-boundaries-border-color",
|
|
7333
|
+
"annotation": "prop",
|
|
7334
|
+
"docs": "Ring of the day under the pointer, not chosen yet (other months).",
|
|
7139
7335
|
"visibility": "internal"
|
|
7140
7336
|
},
|
|
7141
7337
|
{
|
|
7142
7338
|
"name": "--mds-calendar-cell-preselection-other-month-boundaries-color",
|
|
7143
7339
|
"annotation": "prop",
|
|
7144
|
-
"docs": "
|
|
7340
|
+
"docs": "Text color of the day under the pointer (other months).",
|
|
7145
7341
|
"visibility": "internal"
|
|
7146
7342
|
},
|
|
7147
7343
|
{
|
|
7148
7344
|
"name": "--mds-calendar-cell-preselection-other-month-color",
|
|
7149
7345
|
"annotation": "prop",
|
|
7150
|
-
"docs": "Text color
|
|
7346
|
+
"docs": "Text color of the band of a preview (other months).",
|
|
7151
7347
|
"visibility": "internal"
|
|
7152
7348
|
},
|
|
7153
7349
|
{
|
|
@@ -7171,73 +7367,73 @@
|
|
|
7171
7367
|
{
|
|
7172
7368
|
"name": "--mds-calendar-cell-selection-current-month-background",
|
|
7173
7369
|
"annotation": "prop",
|
|
7174
|
-
"docs": "Background
|
|
7370
|
+
"docs": "Background of the band of a range, between and behind its ends (current month).",
|
|
7175
7371
|
"visibility": "internal"
|
|
7176
7372
|
},
|
|
7177
7373
|
{
|
|
7178
7374
|
"name": "--mds-calendar-cell-selection-current-month-boundaries-background",
|
|
7179
7375
|
"annotation": "prop",
|
|
7180
|
-
"docs": "
|
|
7376
|
+
"docs": "Fill of the dot of a chosen day: either end of a range, or the day of a single picker (current month).",
|
|
7181
7377
|
"visibility": "internal"
|
|
7182
7378
|
},
|
|
7183
7379
|
{
|
|
7184
7380
|
"name": "--mds-calendar-cell-selection-current-month-boundaries-color",
|
|
7185
7381
|
"annotation": "prop",
|
|
7186
|
-
"docs": "
|
|
7382
|
+
"docs": "Text color of the dot of a chosen day (current month).",
|
|
7187
7383
|
"visibility": "internal"
|
|
7188
7384
|
},
|
|
7189
7385
|
{
|
|
7190
7386
|
"name": "--mds-calendar-cell-selection-current-month-color",
|
|
7191
7387
|
"annotation": "prop",
|
|
7192
|
-
"docs": "Text color
|
|
7388
|
+
"docs": "Text color of the band of a range (current month).",
|
|
7193
7389
|
"visibility": "internal"
|
|
7194
7390
|
},
|
|
7195
7391
|
{
|
|
7196
7392
|
"name": "--mds-calendar-cell-selection-current-month-weekend-background",
|
|
7197
7393
|
"annotation": "prop",
|
|
7198
|
-
"docs": "Background
|
|
7394
|
+
"docs": "Background of the band of a range on weekend days (current month).",
|
|
7199
7395
|
"visibility": "internal"
|
|
7200
7396
|
},
|
|
7201
7397
|
{
|
|
7202
7398
|
"name": "--mds-calendar-cell-selection-current-month-weekend-boundaries-background",
|
|
7203
7399
|
"annotation": "prop",
|
|
7204
|
-
"docs": "
|
|
7400
|
+
"docs": "Background of the band behind an end of a range on a weekend day.",
|
|
7205
7401
|
"visibility": "internal"
|
|
7206
7402
|
},
|
|
7207
7403
|
{
|
|
7208
7404
|
"name": "--mds-calendar-cell-selection-current-month-weekend-boundaries-color",
|
|
7209
7405
|
"annotation": "prop",
|
|
7210
|
-
"docs": "
|
|
7406
|
+
"docs": "Text color of the dot of an end of a range on a weekend day.",
|
|
7211
7407
|
"visibility": "internal"
|
|
7212
7408
|
},
|
|
7213
7409
|
{
|
|
7214
7410
|
"name": "--mds-calendar-cell-selection-current-month-weekend-color",
|
|
7215
7411
|
"annotation": "prop",
|
|
7216
|
-
"docs": "Text color
|
|
7412
|
+
"docs": "Text color of the band of a range on weekend days (current month).",
|
|
7217
7413
|
"visibility": "internal"
|
|
7218
7414
|
},
|
|
7219
7415
|
{
|
|
7220
7416
|
"name": "--mds-calendar-cell-selection-other-month-background",
|
|
7221
7417
|
"annotation": "prop",
|
|
7222
|
-
"docs": "Background
|
|
7418
|
+
"docs": "Background of the band of a range (other months).",
|
|
7223
7419
|
"visibility": "internal"
|
|
7224
7420
|
},
|
|
7225
7421
|
{
|
|
7226
7422
|
"name": "--mds-calendar-cell-selection-other-month-boundaries-background",
|
|
7227
7423
|
"annotation": "prop",
|
|
7228
|
-
"docs": "
|
|
7424
|
+
"docs": "Fill of the dot of a chosen day (other months).",
|
|
7229
7425
|
"visibility": "internal"
|
|
7230
7426
|
},
|
|
7231
7427
|
{
|
|
7232
7428
|
"name": "--mds-calendar-cell-selection-other-month-boundaries-color",
|
|
7233
7429
|
"annotation": "prop",
|
|
7234
|
-
"docs": "
|
|
7430
|
+
"docs": "Text color of the dot of a chosen day (other months).",
|
|
7235
7431
|
"visibility": "internal"
|
|
7236
7432
|
},
|
|
7237
7433
|
{
|
|
7238
7434
|
"name": "--mds-calendar-cell-selection-other-month-color",
|
|
7239
7435
|
"annotation": "prop",
|
|
7240
|
-
"docs": "Text color
|
|
7436
|
+
"docs": "Text color of the band of a range (other months).",
|
|
7241
7437
|
"visibility": "internal"
|
|
7242
7438
|
},
|
|
7243
7439
|
{
|
|
@@ -7322,9 +7518,9 @@
|
|
|
7322
7518
|
}
|
|
7323
7519
|
],
|
|
7324
7520
|
"usage": {
|
|
7325
|
-
"1. Description": "The `<mds-card>` web component is the surface container of the Magma Design System: a styled, self-contained panel that groups related media, heading, body and action content into a single bounded region. It is a pure layout shell built on named slots and compound children rather than a replacement for any single HTML primitive.\n\n#### Semantic Behavior\n\n- **Layout is inferred, not declared**: The card detects which of the `media` / `header` / `content` / `footer` regions are present, again whenever its content changes, and reshapes itself to whatever content you provide.\n- **Compound parent/child relationship**: `<mds-card-media>`, `<mds-card-header>`, `<mds-card-content>` and `<mds-card-footer>` are recognized by tag name and mapped onto the corresponding region, so they slot in without an explicit `slot` attribute. Plain elements given the matching `slot` value land in that region and take part in the managed grid the same way.\n- **Responsive by width**: The card's internal layout switches between stacked and media-beside-content arrangements based on the card's own width, independent of viewport or theme.\n- **One inset, shared by the regions**: The card pads its regions once, with `--magma-rhythm-inset` (600), and sets them `--magma-rhythm-title-content` (300) apart, so the title of a card stands nearer to its content than to the edge. The regions pad nothing of their own (`rhythm/inset`, `rhythm/shared-inset` in the design language).\n- **The media reaches the edges it touches**: `<mds-card-media>` leaves the inset on the sides where it meets the edge of the card: both sides when the regions are stacked, the top too when no header stands above it, the top, the bottom and the start when it stands beside the content. From the other regions it stands 300, as they do from each other (`rhythm/media-bleed`).\n- **The actions stand apart**: The footer stands `--magma-rhythm-content-actions` (600) from the region before it, as the row of actions of a form or of a dialog: the actions act on the whole card, not on its last line (`rhythm/content-actions`).\n- **The footer closes the card**: The footer region sits at the bottom of the card whatever the other regions are. When the card is taller than its parts (a media taller than header and footer together, or a grid row that stretches a set of cards to one height) and there is no content to take the free space, that space stays above the footer, in the card's background.\n- **Slot regions are fixed**: Only the four named regions are rendered; there is no default (unnamed) slot, so loose text or elements without a recognized slot/tag are not laid out.\n\n#### Properties & Visual Configurations\n\n`<mds-card>` does not use the shared `variant` / `tone` ladders defined in [`agents/variants.md`](../../../../agents/variants.md); it exposes a single behavioral prop.\n\n- **`disableAutoGrid`** (default `false`) toggles the intrinsic responsive grid. Leave it off to let the card own the placement and reflow of its regions; set it to opt out of the managed grid and lay the slotted content out yourself.\n\nThe inset and the gap follow the rhythm roles, so a density theme moves them with every other space. `--mds-card-padding` and `--mds-card-gap` override them for a set of cards, with another rhythm role, never a step; the background of the card and of its regions is `--mds-card-background
|
|
7326
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-card>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Full Card with All Four Regions\n\nThe most common form. Use `<mds-card-header>`, `<mds-card-media>`, `<mds-card-content>`, and `<mds-card-footer>` as direct children. Each compound child self-assigns to its slot - no explicit `slot` attribute needed.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo della scheda</mds-text>\n </mds-card-header>\n <mds-card-media>\n <mds-img src=\"/immagini/copertina.jpg\" alt=\"Copertina del contenuto della scheda\" class=\"object-cover\"></mds-img>\n </mds-card-media>\n <mds-card-content>\n <mds-text>\n Descrizione dettagliata del contenuto della scheda.\n </mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Annulla\"></mds-button>\n <mds-button variant=\"primary\" tone=\"strong\" label=\"Conferma\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Header + Content (No Media)\n\nOmit the regions you do not need - the card detects which regions are present and adapts its grid layout accordingly. A header-and-content-only card stays single-column.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Riepilogo ordine</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>\n Il tuo ordine e' stato elaborato correttamente.\n </mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Media + Content + Footer (No Header)\n\nOmitting the header region shifts media to the top and content immediately below. Useful for image-led catalog cards.\n\n```html\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/immagini/prodotto.jpg\" alt=\"Il prodotto della gamma autunnale\" class=\"object-cover\"></mds-img>\n </mds-card-media>\n <mds-card-content>\n <mds-text>Descrizione prodotto disponibile nella gamma autunnale.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button variant=\"primary\" label=\"Aggiungi al carrello\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Header with Action Button via `mds-card-header`\n\n`<mds-card-header>` has a dedicated `action` slot for icon buttons placed in the trailing position. Use it instead of laying out the button manually.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Profilo utente</mds-text>\n <mds-button\n slot=\"action\"\n icon=\"mi/round/more-vert\"\n aria-label=\"Altre azioni\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Mario Rossi - Amministratore di sistema</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Media with Overlay Content via `mds-card-media`\n\n`<mds-card-media>` exposes a `content` slot that renders in front of the media element. Use it for captions, badges, or status chips overlaid on an image.\n\n```html\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/immagini/evento.jpg\" alt=\"Il palco della conferenza annuale\" class=\"object-cover\"></mds-img>\n <mds-badge slot=\"content\" variant=\"info\" tone=\"strong\">In corso</mds-badge>\n </mds-card-media>\n <mds-card-content>\n <mds-text typography=\"h6\">Conferenza annuale 2025</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Using Raw Slot Attributes Instead of Compound Children\n\nWhen the compound children (`mds-card-*`) do not fit the use case, assign the `slot` attribute directly on any element, with the same four values: `media`, `header`, `content`, and `footer`. The card reads the regions from the `slot` values, so plain elements get the same managed grid and the same inset as the compound children: do not pad them.\n\n```html\n<mds-card>\n <div slot=\"header\" class=\"flex items-center gap-inline\">\n <mds-avatar initials=\"LB\"></mds-avatar>\n <mds-text typography=\"h6\">Luca Bianchi</mds-text>\n </div>\n <mds-img slot=\"media\" src=\"/immagini/lavoro.jpg\" alt=\"Luca Bianchi in cantiere\" class=\"object-cover\"></mds-img>\n <mds-text slot=\"content\">\n Responsabile del progetto infrastrutture.\n </mds-text>\n</mds-card>\n```\n\n#### Disabling the Auto-Grid\n\nSet `disable-auto-grid` to opt out of the managed responsive grid. The regions stack in slot order (media, header, content, footer), whatever their order in the markup, and you own all layout decisions.\n\n```html\n<mds-card disable-auto-grid>\n <mds-card-header>\n <mds-text typography=\"h6\">Layout personalizzato</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Il contenuto e' disposto senza griglia automatica.</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nThe card already takes its inset and its gap from the rhythm roles (`--magma-rhythm-inset`, `--magma-rhythm-title-content`), and a density theme moves them. Set `--mds-card-gap` and `--mds-card-padding` on the host or a parent selector only to give a set of cards another relation of the rhythm, written as its role, never as a step. `--mds-card-background` recolors the card and its regions together; name a surface role so dark mode keeps working.\n\n```css\n.scheda-dati mds-card {\n --mds-card-gap: var(--magma-rhythm-between-fields);\n --mds-card-background: rgb(var(--magma-surface-overlay));\n}\n```\n\n#### Customizing the Layout Part\n\nThe inner grid element is exposed as `::part(layout)`. Use it only for layout-level overrides that the CSS custom properties cannot cover, such as overriding the `border-radius` of the inner container.\n\n```css\n.scheda-highlight mds-card::part(layout) {\n border-radius: var(--magma-radius-xl);\n}\n```\n",
|
|
7327
|
-
"3. Mistakes": "Common incorrect uses of `<mds-card>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Put Content Outside the Four Named Slots\n\n`<mds-card>` has no default (unnamed) slot. Loose text or elements placed without a recognized `slot` attribute - or without using an `mds-card-*` compound child - are silently ignored and never rendered.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <p>Questo testo non verra' mai visualizzato.</p>\n <mds-button label=\"Azione\"></mds-button>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-content>\n <mds-text>Questo testo e' correttamente posizionato nel content slot.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button label=\"Azione\" variant=\"primary\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Do Not Use `mds-card-*` Children Outside `<mds-card>`\n\nCompound children (`mds-card-header`, `mds-card-media`, `mds-card-content`, `mds-card-footer`) rely on `<mds-card>` for layout context. Used standalone they render without the managed grid and without the card's visual chrome.\n\n```html\n<!-- INCORRECT -->\n<div class=\"mia-sezione\">\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo standalone</mds-text>\n </mds-card-header>\n</div>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo nella scheda</mds-text>\n </mds-card-header>\n</mds-card>\n```\n\n#### Do Not Pierce the Shadow DOM with Undocumented Selectors\n\nThe only supported customization surface is `--mds-card-background`, `--mds-card-gap`, `--mds-card-padding`, and `::part(layout)`. Targeting internal class names with `>>>`, `/deep/`, or any selector that reaches inside the shadow root couples your code to implementation details and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-card >>> .layout {\n padding: 16px;\n}\nmds-card .layout--cfhm {\n grid-template-columns: 1fr 1fr;\n}\n\n/* CORRECT */\nmds-card {\n --mds-card-padding: calc(var(--spacing) * 400);\n}\nmds-card::part(layout) {\n border-radius: var(--magma-radius-xl);\n}\n```\n\n#### Do Not Assign an Explicit `slot` Attribute to `mds-card-*` Children\n\n`mds-card-header`, `mds-card-media`, `mds-card-content`, and `mds-card-footer` already set their own `slot` attribute on the host element from inside the component. Adding it again from the outside is redundant and may conflict with internal wiring.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-header slot=\"header\">...</mds-card-header>\n <mds-card-content slot=\"content\">...</mds-card-content>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-header>...</mds-card-header>\n <mds-card-content>...</mds-card-content>\n</mds-card>\n```\n\n#### Do Not Put Media Elements Directly in the `header` Slot\n\nThe `header` slot is intended for title and action controls. Placing an `<mds-img>` or `<img>` directly there bypasses the media region's responsive two-column behavior. Use the `media` slot (or `<mds-card-media>`) for images and videos.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-img src=\"/immagini/banner.jpg\" alt=\"Banner della campagna\"></mds-img>\n </mds-card-header>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/immagini/banner.jpg\" alt=\"Banner della campagna\" class=\"object-cover\"></mds-img>\n </mds-card-media>\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo della scheda</mds-text>\n </mds-card-header>\n</mds-card>\n```\n\n#### Do Not Pad the Regions of a Card\n\nThe card pads its regions once, with its inset. A padding on a region, or on a plain element in a slot, adds to the inset: the title moves away from the edge and from its content, as when every region padded `p-400` of its own and the title stood 800 from its text. A padding on the media also takes it away from the edges it should reach.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-header class=\"p-400\">\n <mds-text typography=\"h6\">Riepilogo ordine</mds-text>\n </mds-card-header>\n <mds-text slot=\"content\" class=\"px-400\">Il tuo ordine e' stato elaborato correttamente.</mds-text>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Riepilogo ordine</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Il tuo ordine e' stato elaborato correttamente.</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Do Not Override Card Dimensions with Inline Styles\n\n`<mds-card>` manages its own min-height and responsive grid. A fixed `height` clips the regions (the card hides its overflow), and a fixed `width` pins the container-query layout instead of letting it follow the space its container gives.\n\n```html\n<!-- INCORRECT -->\n<mds-card style=\"width: 300px; height: 200px;\">\n ...\n</mds-card>\n\n<!-- CORRECT: size the card from a parent container or CSS custom properties -->\n<div class=\"w-[300px]\">\n <mds-card>\n ...\n </mds-card>\n</div>\n```\n"
|
|
7521
|
+
"1. Description": "The `<mds-card>` web component is the surface container of the Magma Design System: a styled, self-contained panel that groups related media, heading, body and action content into a single bounded region. It is a pure layout shell built on named slots and compound children rather than a replacement for any single HTML primitive.\n\n#### Semantic Behavior\n\n- **Layout is inferred, not declared**: The card detects which of the `media` / `header` / `content` / `footer` regions are present, again whenever its content changes, and reshapes itself to whatever content you provide.\n- **Compound parent/child relationship**: `<mds-card-media>`, `<mds-card-header>`, `<mds-card-content>` and `<mds-card-footer>` are recognized by tag name and mapped onto the corresponding region, so they slot in without an explicit `slot` attribute. Plain elements given the matching `slot` value land in that region and take part in the managed grid the same way.\n- **Responsive by width**: The card's internal layout switches between stacked and media-beside-content arrangements based on the card's own width, independent of viewport or theme.\n- **One inset, shared by the regions**: The card pads its regions once, with `--magma-rhythm-inset` (600), and sets them `--magma-rhythm-title-content` (300) apart, so the title of a card stands nearer to its content than to the edge. The regions pad nothing of their own (`rhythm/inset`, `rhythm/shared-inset` in the design language).\n- **The media reaches the edges it touches**: `<mds-card-media>` leaves the inset on the sides where it meets the edge of the card: both sides when the regions are stacked, the top too when no header stands above it, the top, the bottom and the start when it stands beside the content. From the other regions it stands 300, as they do from each other (`rhythm/media-bleed`).\n- **The actions stand apart**: The footer stands `--magma-rhythm-content-actions` (600) from the region before it, as the row of actions of a form or of a dialog: the actions act on the whole card, not on its last line (`rhythm/content-actions`).\n- **The footer closes the card**: The footer region sits at the bottom of the card whatever the other regions are. When the card is taller than its parts (a media taller than header and footer together, or a grid row that stretches a set of cards to one height) and there is no content to take the free space, that space stays above the footer, in the card's background.\n- **The card sets the text of its own surface**: It paints `surface-raised` and sets its `color` to `text-default`, the pair the contrast gate measures, so its regions inherit the text of the card, not the colour of what the card stands on: on a band of colour (`surfaces/intro-band`) its text keeps reading without a reset. A `text-*` class or a `color` on the host still wins.\n- **Slot regions are fixed**: Only the four named regions are rendered; there is no default (unnamed) slot, so loose text or elements without a recognized slot/tag are not laid out.\n\n#### Properties & Visual Configurations\n\n`<mds-card>` does not use the shared `variant` / `tone` ladders defined in [`agents/variants.md`](../../../../agents/variants.md); it exposes a single behavioral prop.\n\n- **`disableAutoGrid`** (default `false`) toggles the intrinsic responsive grid. Leave it off to let the card own the placement and reflow of its regions; set it to opt out of the managed grid and lay the slotted content out yourself.\n\nThe inset and the gap follow the rhythm roles, so a density theme moves them with every other space. `--mds-card-padding` and `--mds-card-gap` override them for a set of cards, with another rhythm role, never a step; the background of the card and of its regions is `--mds-card-background`, its text `--mds-card-color`: set them together, so the text keeps reading on the surface.\n",
|
|
7522
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-card>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Full Card with All Four Regions\n\nThe most common form. Use `<mds-card-header>`, `<mds-card-media>`, `<mds-card-content>`, and `<mds-card-footer>` as direct children. Each compound child self-assigns to its slot - no explicit `slot` attribute needed.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo della scheda</mds-text>\n </mds-card-header>\n <mds-card-media>\n <mds-img src=\"/immagini/copertina.jpg\" alt=\"Copertina del contenuto della scheda\" class=\"object-cover\"></mds-img>\n </mds-card-media>\n <mds-card-content>\n <mds-text>\n Descrizione dettagliata del contenuto della scheda.\n </mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button variant=\"dark\" tone=\"text\" label=\"Annulla\"></mds-button>\n <mds-button variant=\"primary\" tone=\"strong\" label=\"Conferma\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Header + Content (No Media)\n\nOmit the regions you do not need - the card detects which regions are present and adapts its grid layout accordingly. A header-and-content-only card stays single-column.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Riepilogo ordine</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>\n Il tuo ordine e' stato elaborato correttamente.\n </mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Media + Content + Footer (No Header)\n\nOmitting the header region shifts media to the top and content immediately below. Useful for image-led catalog cards.\n\n```html\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/immagini/prodotto.jpg\" alt=\"Il prodotto della gamma autunnale\" class=\"object-cover\"></mds-img>\n </mds-card-media>\n <mds-card-content>\n <mds-text>Descrizione prodotto disponibile nella gamma autunnale.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button variant=\"primary\" label=\"Aggiungi al carrello\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Header with Action Button via `mds-card-header`\n\n`<mds-card-header>` has a dedicated `action` slot for icon buttons placed in the trailing position. Use it instead of laying out the button manually.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Profilo utente</mds-text>\n <mds-button\n slot=\"action\"\n icon=\"mi/round/more-vert\"\n aria-label=\"Altre azioni\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Mario Rossi - Amministratore di sistema</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Media with Overlay Content via `mds-card-media`\n\n`<mds-card-media>` exposes a `content` slot that renders in front of the media element. Use it for captions, badges, or status chips overlaid on an image.\n\n```html\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/immagini/evento.jpg\" alt=\"Il palco della conferenza annuale\" class=\"object-cover\"></mds-img>\n <mds-badge slot=\"content\" variant=\"info\" tone=\"strong\">In corso</mds-badge>\n </mds-card-media>\n <mds-card-content>\n <mds-text typography=\"h6\">Conferenza annuale 2025</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Using Raw Slot Attributes Instead of Compound Children\n\nWhen the compound children (`mds-card-*`) do not fit the use case, assign the `slot` attribute directly on any element, with the same four values: `media`, `header`, `content`, and `footer`. The card reads the regions from the `slot` values, so plain elements get the same managed grid and the same inset as the compound children: do not pad them.\n\n```html\n<mds-card>\n <div slot=\"header\" class=\"flex items-center gap-inline\">\n <mds-avatar initials=\"LB\"></mds-avatar>\n <mds-text typography=\"h6\">Luca Bianchi</mds-text>\n </div>\n <mds-img slot=\"media\" src=\"/immagini/lavoro.jpg\" alt=\"Luca Bianchi in cantiere\" class=\"object-cover\"></mds-img>\n <mds-text slot=\"content\">\n Responsabile del progetto infrastrutture.\n </mds-text>\n</mds-card>\n```\n\n#### Disabling the Auto-Grid\n\nSet `disable-auto-grid` to opt out of the managed responsive grid. The regions stack in slot order (media, header, content, footer), whatever their order in the markup, and you own all layout decisions.\n\n```html\n<mds-card disable-auto-grid>\n <mds-card-header>\n <mds-text typography=\"h6\">Layout personalizzato</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Il contenuto e' disposto senza griglia automatica.</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nThe card already takes its inset and its gap from the rhythm roles (`--magma-rhythm-inset`, `--magma-rhythm-title-content`), and a density theme moves them. Set `--mds-card-gap` and `--mds-card-padding` on the host or a parent selector only to give a set of cards another relation of the rhythm, written as its role, never as a step. `--mds-card-background` recolors the card and its regions together, `--mds-card-color` their text (`text-default` by default); name a surface role and the text role that reads on it, so dark mode keeps working.\n\n```css\n.scheda-dati mds-card {\n --mds-card-gap: var(--magma-rhythm-between-fields);\n --mds-card-background: rgb(var(--magma-surface-overlay));\n}\n\n.scheda-invertita mds-card {\n --mds-card-background: rgb(var(--magma-surface-inverse));\n --mds-card-color: rgb(var(--magma-on-inverse));\n}\n```\n\n#### Customizing the Layout Part\n\nThe inner grid element is exposed as `::part(layout)`. Use it only for layout-level overrides that the CSS custom properties cannot cover, such as overriding the `border-radius` of the inner container.\n\n```css\n.scheda-highlight mds-card::part(layout) {\n border-radius: var(--magma-radius-xl);\n}\n```\n",
|
|
7523
|
+
"3. Mistakes": "Common incorrect uses of `<mds-card>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Put Content Outside the Four Named Slots\n\n`<mds-card>` has no default (unnamed) slot. Loose text or elements placed without a recognized `slot` attribute - or without using an `mds-card-*` compound child - are silently ignored and never rendered.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <p>Questo testo non verra' mai visualizzato.</p>\n <mds-button label=\"Azione\"></mds-button>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-content>\n <mds-text>Questo testo e' correttamente posizionato nel content slot.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button label=\"Azione\" variant=\"primary\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Do Not Use `mds-card-*` Children Outside `<mds-card>`\n\nCompound children (`mds-card-header`, `mds-card-media`, `mds-card-content`, `mds-card-footer`) rely on `<mds-card>` for layout context. Used standalone they render without the managed grid and without the card's visual chrome.\n\n```html\n<!-- INCORRECT -->\n<div class=\"mia-sezione\">\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo standalone</mds-text>\n </mds-card-header>\n</div>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo nella scheda</mds-text>\n </mds-card-header>\n</mds-card>\n```\n\n#### Do Not Pierce the Shadow DOM with Undocumented Selectors\n\nThe only supported customization surface is `--mds-card-background`, `--mds-card-color`, `--mds-card-gap`, `--mds-card-padding`, and `::part(layout)`. Targeting internal class names with `>>>`, `/deep/`, or any selector that reaches inside the shadow root couples your code to implementation details and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-card >>> .layout {\n padding: 16px;\n}\nmds-card .layout--cfhm {\n grid-template-columns: 1fr 1fr;\n}\n\n/* CORRECT */\nmds-card {\n --mds-card-padding: calc(var(--spacing) * 400);\n}\nmds-card::part(layout) {\n border-radius: var(--magma-radius-xl);\n}\n```\n\n#### Do Not Assign an Explicit `slot` Attribute to `mds-card-*` Children\n\n`mds-card-header`, `mds-card-media`, `mds-card-content`, and `mds-card-footer` already set their own `slot` attribute on the host element from inside the component. Adding it again from the outside is redundant and may conflict with internal wiring.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-header slot=\"header\">...</mds-card-header>\n <mds-card-content slot=\"content\">...</mds-card-content>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-header>...</mds-card-header>\n <mds-card-content>...</mds-card-content>\n</mds-card>\n```\n\n#### Do Not Put Media Elements Directly in the `header` Slot\n\nThe `header` slot is intended for title and action controls. Placing an `<mds-img>` or `<img>` directly there bypasses the media region's responsive two-column behavior. Use the `media` slot (or `<mds-card-media>`) for images and videos.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-img src=\"/immagini/banner.jpg\" alt=\"Banner della campagna\"></mds-img>\n </mds-card-header>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/immagini/banner.jpg\" alt=\"Banner della campagna\" class=\"object-cover\"></mds-img>\n </mds-card-media>\n <mds-card-header>\n <mds-text typography=\"h6\">Titolo della scheda</mds-text>\n </mds-card-header>\n</mds-card>\n```\n\n#### Do Not Pad the Regions of a Card\n\nThe card pads its regions once, with its inset. A padding on a region, or on a plain element in a slot, adds to the inset: the title moves away from the edge and from its content, as when every region padded `p-400` of its own and the title stood 800 from its text. A padding on the media also takes it away from the edges it should reach.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-header class=\"p-400\">\n <mds-text typography=\"h6\">Riepilogo ordine</mds-text>\n </mds-card-header>\n <mds-text slot=\"content\" class=\"px-400\">Il tuo ordine e' stato elaborato correttamente.</mds-text>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Riepilogo ordine</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Il tuo ordine e' stato elaborato correttamente.</mds-text>\n </mds-card-content>\n</mds-card>\n```\n\n#### Do Not Override Card Dimensions with Inline Styles\n\n`<mds-card>` manages its own min-height and responsive grid. A fixed `height` clips the regions (the card hides its overflow), and a fixed `width` pins the container-query layout instead of letting it follow the space its container gives.\n\n```html\n<!-- INCORRECT -->\n<mds-card style=\"width: 300px; height: 200px;\">\n ...\n</mds-card>\n\n<!-- CORRECT: size the card from a parent container or CSS custom properties -->\n<div class=\"w-[300px]\">\n <mds-card>\n ...\n </mds-card>\n</div>\n```\n"
|
|
7328
7524
|
},
|
|
7329
7525
|
"props": [
|
|
7330
7526
|
{
|
|
@@ -7367,6 +7563,12 @@
|
|
|
7367
7563
|
"docs": "Sets the background color of the card and of its regions (`mds-card-header`, `mds-card-media`, `mds-card-content`, `mds-card-footer`)",
|
|
7368
7564
|
"visibility": "public"
|
|
7369
7565
|
},
|
|
7566
|
+
{
|
|
7567
|
+
"name": "--mds-card-color",
|
|
7568
|
+
"annotation": "prop",
|
|
7569
|
+
"docs": "Sets the text color of the card, inherited by its regions, `--magma-text-default` by default: set it together with `--mds-card-background`, so the text keeps reading on the surface",
|
|
7570
|
+
"visibility": "public"
|
|
7571
|
+
},
|
|
7370
7572
|
{
|
|
7371
7573
|
"name": "--mds-card-gap",
|
|
7372
7574
|
"annotation": "prop",
|
|
@@ -7466,8 +7668,8 @@
|
|
|
7466
7668
|
}
|
|
7467
7669
|
],
|
|
7468
7670
|
"usage": {
|
|
7469
|
-
"1. Description": "The `<mds-card-footer>` web component is the footer region of a [`<mds-card>`](../mds-card/AGENTS.md), grouping the trailing content of a card (typically actions such as buttons or supplementary metadata) into the card's bottom region.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-card-footer>` must be a direct slot child of `<mds-card>`; it is not used standalone, nor mixed in as a different child type.\n- **Self-slotting**: Simply placing it inside `<mds-card>` routes it into the parent's footer region without the author setting the slot manually.\n- **Pure layout wrapper**: It has a single default slot and no props, no state, no events, and no ARIA role of its own. It contributes only structural placement, not semantics.\n- **A row of actions**: the actions stand `rhythm/inline` apart at the end of the card; under `--magma-container-actions` of the footer (380px) they stack, each at the full width, in the order of the row, the main action at the bottom (`actions/stacked`).\n- **Presence affects parent layout**: Including or omitting the footer changes how the card arranges its regions.\n\n#### Slot semantics\n\nThis component exposes a single default slot and has no configurable properties. Pass any `text`, `HTML elements`, or other components (commonly `<mds-button>` actions) into the default slot; they will be rendered in the card's footer region. The footer lays its children out in a row aligned to the end, with a fixed gap and padding; the placement of the region and the responsive behavior are owned by the parent `<mds-card>`.\n",
|
|
7470
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-card-footer>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Action Row Inside a Full Card\n\nThe typical use: a card with header, content, and footer regions, the footer holding the primary and secondary actions. Place `<mds-card-footer>` as a direct child of `<mds-card>` - it routes itself to the footer region automatically.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Riepilogo pratica</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Verifica i dati prima di procedere.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button label=\"Conferma\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Single Call-to-Action\n\nA card with only a media region and a footer is a valid minimal composition. The footer carries a lone action.\n\n```html\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/images/documento.jpg\" alt=\"Anteprima documento\"></mds-img>\n </mds-card-media>\n <mds-card-footer>\n <mds-button label=\"Scarica\" icon=\"mi/baseline/download\" variant=\"primary\" tone=\"weak\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Destructive Action Pattern\n\nUse a `variant=\"error\"` button for destructive operations. Keep the cancel action to the left and the destructive action to the right - the footer's `justify-content: flex-end` naturally aligns both.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Elimina archivio</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Questa operazione non puo essere annullata.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Supplementary Metadata Alongside an Action\n\nThe default slot accepts any slottable content - mix an informational label with a button when status context belongs at the bottom of the card.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Stato richiesta</mds-text>\n </mds-card-header>\n <mds-card-footer>\n <mds-badge label=\"In attesa\" variant=\"warning\" tone=\"weak\"></mds-badge>\n <mds-button label=\"Visualizza dettagli\" variant=\"primary\" tone=\"outline\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Explicit `slot` Attribute on a Plain Element\n\nWhen you prefer a plain `<div>` or need to place a non-`mds-card-*` wrapper in the footer region, set `slot=\"footer\"` explicitly. The element lands in the footer region, but `<mds-card>` infers its managed grid from the tag names of its children: add `disable-auto-grid` to the card, otherwise the regions overlap.\n\n```html\n<mds-card disable-auto-grid>\n <mds-card-header>\n <mds-text typography=\"h6\">Nota operativa</mds-text>\n </mds-card-header>\n <div slot=\"footer\" style=\"display: flex; gap: calc(var(--spacing) * 300);\">\n <mds-button label=\"Chiudi\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button label=\"Salva nota\" variant=\"primary\" tone=\"strong\"></mds-button>\n </div>\n</mds-card>\n```\n",
|
|
7671
|
+
"1. Description": "The `<mds-card-footer>` web component is the footer region of a [`<mds-card>`](../mds-card/AGENTS.md), grouping the trailing content of a card (typically actions such as buttons or supplementary metadata) into the card's bottom region.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-card-footer>` must be a direct slot child of `<mds-card>`; it is not used standalone, nor mixed in as a different child type.\n- **Self-slotting**: Simply placing it inside `<mds-card>` routes it into the parent's footer region without the author setting the slot manually.\n- **Pure layout wrapper**: It has a single default slot and no props, no state, no events, and no ARIA role of its own. It contributes only structural placement, not semantics.\n- **A row of actions**: the actions stand `rhythm/inline` apart at the end of the card; under `--magma-container-actions` of the footer (380px) they stack, each at the full width, in the order of the row, the main action at the bottom (`actions/stacked`). A lone action has no order to keep: it stays at its own width at the end of the row at every width, as an `<mds-button-dropdown>` alone does, so a grid of narrow cards does not repeat a band of buttons.\n- **Presence affects parent layout**: Including or omitting the footer changes how the card arranges its regions.\n\n#### Slot semantics\n\nThis component exposes a single default slot and has no configurable properties. Pass any `text`, `HTML elements`, or other components (commonly `<mds-button>` actions) into the default slot; they will be rendered in the card's footer region. The footer lays its children out in a row aligned to the end, with a fixed gap and padding; the placement of the region and the responsive behavior are owned by the parent `<mds-card>`.\n",
|
|
7672
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-card-footer>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Action Row Inside a Full Card\n\nThe typical use: a card with header, content, and footer regions, the footer holding the primary and secondary actions. Place `<mds-card-footer>` as a direct child of `<mds-card>` - it routes itself to the footer region automatically.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Riepilogo pratica</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Verifica i dati prima di procedere.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button label=\"Conferma\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Single Call-to-Action\n\nA card with only a media region and a footer is a valid minimal composition. The footer carries a lone action, which keeps its own width at the end of the row even when the footer is under `--magma-container-actions` (380px): with one action the stack has no order to keep, so it does not stretch it.\n\n```html\n<mds-card>\n <mds-card-media>\n <mds-img src=\"/images/documento.jpg\" alt=\"Anteprima documento\"></mds-img>\n </mds-card-media>\n <mds-card-footer>\n <mds-button label=\"Scarica\" icon=\"mi/baseline/download\" variant=\"primary\" tone=\"weak\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Destructive Action Pattern\n\nUse a `variant=\"error\"` button for destructive operations. Keep the cancel action to the left and the destructive action to the right - the footer's `justify-content: flex-end` naturally aligns both.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Elimina archivio</mds-text>\n </mds-card-header>\n <mds-card-content>\n <mds-text>Questa operazione non puo essere annullata.</mds-text>\n </mds-card-content>\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Supplementary Metadata Alongside an Action\n\nThe default slot accepts any slottable content - mix an informational label with a button when status context belongs at the bottom of the card.\n\n```html\n<mds-card>\n <mds-card-header>\n <mds-text typography=\"h6\">Stato richiesta</mds-text>\n </mds-card-header>\n <mds-card-footer>\n <mds-badge label=\"In attesa\" variant=\"warning\" tone=\"weak\"></mds-badge>\n <mds-button label=\"Visualizza dettagli\" variant=\"primary\" tone=\"outline\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Explicit `slot` Attribute on a Plain Element\n\nWhen you prefer a plain `<div>` or need to place a non-`mds-card-*` wrapper in the footer region, set `slot=\"footer\"` explicitly. The element lands in the footer region, but `<mds-card>` infers its managed grid from the tag names of its children: add `disable-auto-grid` to the card, otherwise the regions overlap.\n\n```html\n<mds-card disable-auto-grid>\n <mds-card-header>\n <mds-text typography=\"h6\">Nota operativa</mds-text>\n </mds-card-header>\n <div slot=\"footer\" style=\"display: flex; gap: calc(var(--spacing) * 300);\">\n <mds-button label=\"Chiudi\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button label=\"Salva nota\" variant=\"primary\" tone=\"strong\"></mds-button>\n </div>\n</mds-card>\n```\n",
|
|
7471
7673
|
"3. Mistakes": "Common incorrect uses of `<mds-card-footer>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-card-footer>` Outside `<mds-card>`\n\n`<mds-card-footer>` self-routes to the `footer` slot of `<mds-card>` via `<Host slot=\"footer\">`. Outside a card it renders as a bare flex row with no visual context and communicates nothing to screen readers.\n\n```html\n<!-- INCORRECT -->\n<mds-card-footer>\n <mds-button label=\"Conferma\" variant=\"primary\"></mds-button>\n</mds-card-footer>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-footer>\n <mds-button label=\"Conferma\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Do Not Assign `slot=\"footer\"` on `<mds-card-footer>` Manually\n\n`<mds-card-footer>` already sets `slot=\"footer\"` on its host via its own render output. Adding it again as an attribute in your markup is redundant: the component writes it itself, overwriting any other value when it renders.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-footer slot=\"footer\">\n <mds-button label=\"Salva\" variant=\"primary\"></mds-button>\n </mds-card-footer>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-footer>\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Do Not Nest `<mds-card-footer>` Inside a Wrapper Element\n\nCompound component children must be direct slot children of the parent - `<mds-card>` has no default slot, so a `<div>` wrapper without a `slot` is not rendered at all, and the `<mds-card-footer>` inside it with it.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <div class=\"azioni\">\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\"></mds-button>\n </mds-card-footer>\n </div>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Do Not Place Multiple `<mds-card-footer>` in One Card\n\n`<mds-card>` maps all children with the footer tag to the same grid area; multiple footers stack or overlap unpredictably. Consolidate all footer content into a single `<mds-card-footer>`.\n\n```html\n<!-- INCORRECT -->\n<mds-card>\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\"></mds-button>\n </mds-card-footer>\n <mds-card-footer>\n <mds-button label=\"Conferma\" variant=\"primary\"></mds-button>\n </mds-card-footer>\n</mds-card>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-footer>\n <mds-button label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n <mds-button label=\"Conferma\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n\n#### Do Not Override Footer Layout via Inline Styles or Undocumented Selectors\n\n`<mds-card-footer>` owns its internal flex layout (the alignment at the end, the actions `--magma-rhythm-inline` apart); its inset is the card's, and the card sets it `--magma-rhythm-content-actions` from the region before it. Overriding it with inline `style` or by targeting shadow internals breaks theme consistency and couples code to implementation details. If the parent card's spacing must change, use `<mds-card>`'s documented `--mds-card-gap` and `--mds-card-padding` custom properties on the card host, with a rhythm role.\n\n```html\n<!-- INCORRECT -->\n<mds-card-footer style=\"justify-content: flex-start; padding: 0;\">\n <mds-button label=\"Salva\" variant=\"primary\"></mds-button>\n</mds-card-footer>\n\n<!-- CORRECT -->\n<mds-card>\n <mds-card-footer>\n <mds-button label=\"Salva\" variant=\"primary\" tone=\"strong\"></mds-button>\n </mds-card-footer>\n</mds-card>\n```\n"
|
|
7472
7674
|
},
|
|
7473
7675
|
"props": [],
|
|
@@ -7604,9 +7806,9 @@
|
|
|
7604
7806
|
}
|
|
7605
7807
|
],
|
|
7606
7808
|
"usage": {
|
|
7607
|
-
"1. Description": "The `<mds-chip>` web component is the Magma Design System's compact element for representing a discrete piece of information, a filter, a selection, or a removable token. It renders a label with optional leading icon and an optional delete affordance, and can be made interactive (clickable or selectable) to act as a lightweight button-like control rather than a static tag.\n\n#### Semantic Behavior\n\n- **Static by default**: With no interaction props the chip is a passive, non-focusable label; it becomes a focusable, button-like control only when `clickable` is set.\n- **Selectable implies clickable**: Setting `selectable` automatically turns on `clickable`, so a selectable chip is always keyboard- and pointer-interactive.\n- **Selection toggle**: When `selectable`, activating the chip flips `selected`; an unselected chip carries no `selected` attribute (rather than `selected=\"false\"`).\n- **Keyboard activation**: When interactive, Enter and Space activate the chip just like a pointer click.\n- **Delete affordance**: When `deletable`, a trailing delete button is rendered with a localized title (el/en/es/it) and emits the delete event on activation.\n- **Emitted events**: `mdsChipClickLabel` fires on activation for non-selectable chips, `mdsChipSelect` fires (carrying the new `selected` value) for selectable chips, and `mdsChipDelete` fires from the delete button - all carrying the originating event and host element.\n- **Label is text, on one line**: Long labels do not wrap (`truncate=\"word\"` on the inner text).\n\n#### Properties & Visual Configurations\n\nThe shared `variant` / `tone` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md); the chip defaults to `variant=\"primary\"` and `tone=\"strong\"`, and accepts only the minimal `'strong'` / `'weak'` tone set. `variant` and `tone` paint the leading icon badge and the border of a selected chip; the body of the chip stays neutral for every variant.\n\n#### Other behavioral props\n\n- **`clickable`** opts the chip into interactivity (focus, keyboard and click handling) without changing its state on activation - use it for chips that act as actions rather than toggles.\n- **`selectable`** makes the chip a toggle whose `selected` state flips on each activation; pick it for filter/choice chips where the visual selected state matters.\n- **`selected`** drives the selected visual treatment and can be set externally to pre-select a chip; an unselected chip carries no attribute.\n- **`deletable`** adds the trailing cancel button for removable tokens; reserve it for chips the user is meant to dismiss.\n- **`icon`** is an SVG filename slug from the Magma icon library, shown decoratively to the left of the label.\n",
|
|
7608
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-chip>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Static Tag (Label Only)\n\nThe simplest form. Use the required `label` prop to display a read-only tag. With no interaction props the chip is passive and non-focusable.\n\n```html\n<mds-chip label=\"In lavorazione\" variant=\"warning\" tone=\"strong\"></mds-chip>\n```\n\n#### Variant and Tone for Semantic Emphasis\n\nPair the same `variant` with a different `tone` to express importance or category. Do not invent custom colors to dim or saturate. The variant paints the leading icon badge (and the border of a selected chip), not the body of the chip: give the chip an `icon` when its color has to carry meaning.\n\n```html\n<!-- Status chips -->\n<mds-chip label=\"Completato\" icon=\"mi/baseline/check-circle\" variant=\"success\" tone=\"strong\"></mds-chip>\n<mds-chip label=\"In attesa\" icon=\"mi/baseline/schedule\" variant=\"warning\" tone=\"weak\"></mds-chip>\n<mds-chip label=\"Errore\" icon=\"mi/baseline/error\" variant=\"error\" tone=\"strong\"></mds-chip>\n\n<!-- Decorative label chips -->\n<mds-chip label=\"Natura\" icon=\"mi/baseline/eco\" variant=\"green\" tone=\"weak\"></mds-chip>\n<mds-chip label=\"Tecnologia\" icon=\"mi/baseline/computer\" variant=\"blue\" tone=\"strong\"></mds-chip>\n```\n\n#### Chip with Leading Icon\n\nReference icons by their filename slug (no `.svg` extension). The icon is rendered decoratively to the left of the label inside a circular badge.\n\n```html\n<mds-chip\n label=\"Animali\"\n icon=\"mi/baseline/pets\"\n variant=\"primary\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Clickable Chip (Action, No Toggle)\n\nUse `clickable` when the chip triggers an action but does not need a persistent selected state. The component adds `role=\"button\"`, focus handling, and keyboard activation. Listen for `mdsChipClickLabel`.\n\n```html\n<mds-chip\n label=\"Apri dettagli\"\n clickable\n icon=\"mi/baseline/open-in-new\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipClickLabel', (e) => {\n console.log('clicked', e.detail.element);\n });\n</script>\n```\n\n#### Selectable Chip (Toggle)\n\nUse `selectable` for filter or choice chips where the visual selected state matters. `selectable` implies `clickable` automatically. Activating the chip flips `selected`; the event `mdsChipSelect` carries the new value in `e.detail.selected` (`true`, or `undefined` when deselected).\n\n```html\n<mds-chip\n label=\"Vegetariano\"\n selectable\n icon=\"mi/baseline/eco\"\n variant=\"success\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipSelect', (e) => {\n console.log('selezionato:', e.detail.selected);\n });\n</script>\n```\n\n#### Pre-selected Chip\n\nSet `selected` externally to initialize a selectable chip in the selected state (e.g. when restoring saved filter state). An unselected chip carries no `selected` attribute.\n\n```html\n<mds-chip\n label=\"Urgente\"\n selectable\n selected\n variant=\"error\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Deletable Chip (Removable Token)\n\nUse `deletable` for chips the user is meant to dismiss - for example tags on an entity or active filters. A trailing cancel button emits `mdsChipDelete` on activation.\n\n```html\n<mds-chip\n label=\"Mario Rossi\"\n deletable\n icon=\"mi/baseline/person\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipDelete', (e) => {\n e.detail.element.remove();\n });\n</script>\n```\n\n#### Fully Interactive Chip\n\nCombine `clickable` (or `selectable`) with `deletable` for chips that can both be activated and removed independently.\n\n```html\n<mds-chip\n label=\"Sport invernali\"\n clickable\n deletable\n icon=\"mi/baseline/downhill-skiing\"\n variant=\"info\"\n tone=\"weak\"\n></mds-chip>\n```\n\n#### Disabled Chip\n\nSet `disabled` to dim the chip and block it: a clickable label leaves the tab order and takes `aria-disabled=\"true\"`, the delete button is disabled, and neither the pointer nor the keyboard fires an event. The prop is reflected, so setting it from code styles the chip too. Do not use `disabled=\"false\"` - remove the attribute to re-enable.\n\n```html\n<mds-chip\n label=\"Non disponibile\"\n disabled\n variant=\"dark\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Styling Customization\n\nStyle the chip only through its public `--mds-chip-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode, named themes and high contrast keep working. When `selected` is set the component swaps each property for a selected value of its own, which is not public. A property set on the host from outside wins over that swap: scope the resting values to `:not([selected])`, and set the same public properties on `[selected]` to restyle the selected state.\n\n```css\n.filtri-categoria mds-chip:not([selected]) {\n --mds-chip-background: rgb(var(--magma-accent-surface));\n --mds-chip-color: rgb(var(--magma-accent-fg));\n}\n\n.filtri-categoria mds-chip[selected] {\n --mds-chip-background: rgb(var(--magma-accent-emphasis));\n --mds-chip-color: rgb(var(--magma-accent-on-emphasis));\n}\n```\n",
|
|
7609
|
-
"3. Mistakes": "Common incorrect uses of `<mds-chip>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Clickable Chip Without `clickable` or `selectable`\n\nWithout `clickable`, the chip has no `role`, no focus management, and no keyboard activation. Listening for click events on a static chip is a silent accessibility failure.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Apri\" variant=\"primary\" onclick=\"doSomething()\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Apri\" clickable variant=\"primary\"></mds-chip>\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipClickLabel', doSomething);\n</script>\n```\n\n#### Do Not Use `selected` Without `selectable`\n\n`selected` only has visual and semantic meaning when `selectable` is also set. On a non-selectable chip the attribute renders the selected style but the selection can never be toggled and no event fires, misleading users.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Attivo\" selected variant=\"success\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Attivo\" selectable selected variant=\"success\"></mds-chip>\n```\n\n#### Do Not Apply `tone` Values Outside the Minimal Ladder\n\n`mds-chip` accepts only `ToneMinimalVariantType`: `strong` and `weak`. Passing `outline`, `text`, or `box` is invalid: no style matches it, so the chip silently loses its variant colors.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Categoria\" tone=\"outline\" variant=\"primary\"></mds-chip>\n<mds-chip label=\"Categoria\" tone=\"text\" variant=\"primary\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Categoria\" tone=\"weak\" variant=\"primary\"></mds-chip>\n<mds-chip label=\"Categoria\" tone=\"strong\" variant=\"primary\"></mds-chip>\n```\n\n#### Do Not Slot Content Into the Chip\n\n`<mds-chip>` has no default or named slots - all content is driven by props (`label`, `icon`, `deletable`). Slotting HTML children is ignored by the Shadow DOM.\n\n```html\n<!-- INCORRECT -->\n<mds-chip>\n <span>Etichetta</span>\n <mds-icon name=\"mi/baseline/close\"></mds-icon>\n</mds-chip>\n\n<!-- CORRECT -->\n<mds-chip\n label=\"Etichetta\"\n icon=\"mi/baseline/pets\"\n deletable\n variant=\"primary\"\n></mds-chip>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Delete Button\n\nThe inner `mds-button` used for the delete affordance is a Shadow DOM implementation detail with no styling API of its own: targeting it with `>>>` or undocumented `::part()` names will break on minor releases. Restyle the chip and its leading icon through the public `--mds-chip-*` properties.\n\n```css\n/* INCORRECT */\nmds-chip >>> .button-delete {\n color: red;\n}\n\n/* CORRECT */\nmds-chip {\n --mds-chip-icon-background: rgb(var(--magma-danger-emphasis));\n}\n```\n\n#### Do Not Forget to Remove `await`-Pattern Analogue: Removing `selected` by Setting It to `false`\n\nWith `selected=\"false\"` the component reads the prop as `false` and drops the attribute when it renders, but until then the attribute is in the DOM and attribute selectors (`mds-chip[selected]`) match it. Remove the attribute; from JavaScript both `false` and `undefined` deselect the chip (the component turns `false` into `undefined` and drops the attribute).\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Filtro\" selectable selected=\"false\" variant=\"primary\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Filtro\" selectable variant=\"primary\"></mds-chip>\n```\n\n#### Do Not Use `<mds-chip>` as a Navigation Link\n\n`<mds-chip>` has no `href` prop. Wrapping it in an `<a>` creates a nested interactive element, breaks keyboard semantics, and fails accessibility audits. Use [`mds-button`](../mds-button/AGENTS.md) with `href` instead.\n\n```html\n<!-- INCORRECT -->\n<a href=\"/categoria/sport\">\n <mds-chip label=\"Sport\" variant=\"primary\"></mds-chip>\n</a>\n\n<!-- CORRECT -->\n<mds-button\n label=\"Sport\"\n href=\"/categoria/sport\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-button>\n```\n"
|
|
7809
|
+
"1. Description": "The `<mds-chip>` web component is the Magma Design System's compact element for representing a discrete piece of information, a filter, a selection, or a removable token. It renders a label with an optional leading icon or colour swatch and an optional delete affordance, and can be made interactive (clickable or selectable) to act as a lightweight button-like control rather than a static tag.\n\n#### Semantic Behavior\n\n- **Static by default**: With no interaction props the chip is a passive, non-focusable label; it becomes a focusable, button-like control only when `clickable` is set.\n- **Selectable implies clickable**: Setting `selectable` automatically turns on `clickable`, so a selectable chip is always keyboard- and pointer-interactive.\n- **Selection toggle**: When `selectable`, activating the chip flips `selected`; an unselected chip carries no `selected` attribute (rather than `selected=\"false\"`).\n- **Keyboard activation**: When interactive, Enter and Space activate the chip just like a pointer click.\n- **Delete affordance**: When `deletable`, a trailing delete button is rendered with a localized title (el/en/es/it) and emits the delete event on activation.\n- **Emitted events**: `mdsChipClickLabel` fires on activation for non-selectable chips, `mdsChipSelect` fires (carrying the new `selected` value) for selectable chips, and `mdsChipDelete` fires from the delete button - all carrying the originating event and host element.\n- **Label is text, on one line**: Long labels do not wrap (`truncate=\"word\"` on the inner text).\n- **One leading mark**: `swatch` takes the place of `icon`; when both are set the chip draws the swatch. The swatch is decorative and hidden from assistive technologies, so the label has to name the colour.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` / `tone` ladders are defined in [`agents/variants.md`](../../../../agents/variants.md); the chip defaults to `variant=\"primary\"` and `tone=\"strong\"`, and accepts only the minimal `'strong'` / `'weak'` tone set. `variant` and `tone` paint the leading icon badge and the border of a selected chip; the body of the chip stays neutral for every variant.\n\n#### Other behavioral props\n\n- **`clickable`** opts the chip into interactivity (focus, keyboard and click handling) without changing its state on activation - use it for chips that act as actions rather than toggles.\n- **`selectable`** makes the chip a toggle whose `selected` state flips on each activation; pick it for filter/choice chips where the visual selected state matters.\n- **`selected`** drives the selected visual treatment and can be set externally to pre-select a chip; an unselected chip carries no attribute.\n- **`deletable`** adds the trailing cancel button for removable tokens; reserve it for chips the user is meant to dismiss.\n- **`icon`** is an SVG filename slug from the Magma icon library, shown decoratively to the left of the label.\n- **`swatch`** is a colour of the product, any CSS colour, drawn as a round swatch where the icon goes: for chips whose label names a colour (a family of colours, a category, a calendar). It is not a role and does not follow `variant` or the mode: the chip draws it as given, inside a ring that keeps it visible on the chip at rest and selected, in light and dark. A value that is not a colour draws the empty ring.\n",
|
|
7810
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-chip>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Static Tag (Label Only)\n\nThe simplest form. Use the required `label` prop to display a read-only tag. With no interaction props the chip is passive and non-focusable.\n\n```html\n<mds-chip label=\"In lavorazione\" variant=\"warning\" tone=\"strong\"></mds-chip>\n```\n\n#### Variant and Tone for Semantic Emphasis\n\nPair the same `variant` with a different `tone` to express importance or category. Do not invent custom colors to dim or saturate. The variant paints the leading icon badge (and the border of a selected chip), not the body of the chip: give the chip an `icon` when its color has to carry meaning.\n\n```html\n<!-- Status chips -->\n<mds-chip label=\"Completato\" icon=\"mi/baseline/check-circle\" variant=\"success\" tone=\"strong\"></mds-chip>\n<mds-chip label=\"In attesa\" icon=\"mi/baseline/schedule\" variant=\"warning\" tone=\"weak\"></mds-chip>\n<mds-chip label=\"Errore\" icon=\"mi/baseline/error\" variant=\"error\" tone=\"strong\"></mds-chip>\n\n<!-- Decorative label chips -->\n<mds-chip label=\"Natura\" icon=\"mi/baseline/eco\" variant=\"green\" tone=\"weak\"></mds-chip>\n<mds-chip label=\"Tecnologia\" icon=\"mi/baseline/computer\" variant=\"blue\" tone=\"strong\"></mds-chip>\n```\n\n#### Chip with Leading Icon\n\nReference icons by their filename slug (no `.svg` extension). The icon is rendered decoratively to the left of the label inside a circular badge.\n\n```html\n<mds-chip\n label=\"Animali\"\n icon=\"mi/baseline/pets\"\n variant=\"primary\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Chip with a Colour Swatch\n\nUse `swatch` when the label names a colour of the product: a family of colours to turn on and off, a category, a calendar. The value is the product's own, any CSS colour (`#a89586`, `rgb(47 111 208)`, `oklch(70% 0.19 50)`), not a token: the chip draws it as given in every mode, round and where the icon goes, inside a ring that keeps a colour as light or as dark as the chip visible. The swatch is hidden from assistive technologies, so the label names the colour; it takes the place of `icon`.\n\n```html\n<mds-chip label=\"kaolin\" swatch=\"#9aa3ad\" selectable selected></mds-chip>\n<mds-chip label=\"fireclay\" swatch=\"#a89586\" selectable></mds-chip>\n<mds-chip label=\"Calendario ferie\" swatch=\"#2f6fd0\" clickable></mds-chip>\n```\n\n#### Clickable Chip (Action, No Toggle)\n\nUse `clickable` when the chip triggers an action but does not need a persistent selected state. The component adds `role=\"button\"`, focus handling, and keyboard activation. Listen for `mdsChipClickLabel`.\n\n```html\n<mds-chip\n label=\"Apri dettagli\"\n clickable\n icon=\"mi/baseline/open-in-new\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipClickLabel', (e) => {\n console.log('clicked', e.detail.element);\n });\n</script>\n```\n\n#### Selectable Chip (Toggle)\n\nUse `selectable` for filter or choice chips where the visual selected state matters. `selectable` implies `clickable` automatically. Activating the chip flips `selected`; the event `mdsChipSelect` carries the new value in `e.detail.selected` (`true`, or `undefined` when deselected).\n\n```html\n<mds-chip\n label=\"Vegetariano\"\n selectable\n icon=\"mi/baseline/eco\"\n variant=\"success\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipSelect', (e) => {\n console.log('selezionato:', e.detail.selected);\n });\n</script>\n```\n\n#### Pre-selected Chip\n\nSet `selected` externally to initialize a selectable chip in the selected state (e.g. when restoring saved filter state). An unselected chip carries no `selected` attribute.\n\n```html\n<mds-chip\n label=\"Urgente\"\n selectable\n selected\n variant=\"error\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Deletable Chip (Removable Token)\n\nUse `deletable` for chips the user is meant to dismiss - for example tags on an entity or active filters. A trailing cancel button emits `mdsChipDelete` on activation.\n\n```html\n<mds-chip\n label=\"Mario Rossi\"\n deletable\n icon=\"mi/baseline/person\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-chip>\n\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipDelete', (e) => {\n e.detail.element.remove();\n });\n</script>\n```\n\n#### Fully Interactive Chip\n\nCombine `clickable` (or `selectable`) with `deletable` for chips that can both be activated and removed independently.\n\n```html\n<mds-chip\n label=\"Sport invernali\"\n clickable\n deletable\n icon=\"mi/baseline/downhill-skiing\"\n variant=\"info\"\n tone=\"weak\"\n></mds-chip>\n```\n\n#### Disabled Chip\n\nSet `disabled` to dim the chip and block it: a clickable label leaves the tab order and takes `aria-disabled=\"true\"`, the delete button is disabled, and neither the pointer nor the keyboard fires an event. The prop is reflected, so setting it from code styles the chip too. Do not use `disabled=\"false\"` - remove the attribute to re-enable.\n\n```html\n<mds-chip\n label=\"Non disponibile\"\n disabled\n variant=\"dark\"\n tone=\"strong\"\n></mds-chip>\n```\n\n#### Styling Customization\n\nStyle the chip only through its public `--mds-chip-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode, named themes and high contrast keep working. When `selected` is set the component swaps each property for a selected value of its own, which is not public. A property set on the host from outside wins over that swap: scope the resting values to `:not([selected])`, and set the same public properties on `[selected]` to restyle the selected state.\n\n```css\n.filtri-categoria mds-chip:not([selected]) {\n --mds-chip-background: rgb(var(--magma-accent-surface));\n --mds-chip-color: rgb(var(--magma-accent-fg));\n}\n\n.filtri-categoria mds-chip[selected] {\n --mds-chip-background: rgb(var(--magma-accent-emphasis));\n --mds-chip-color: rgb(var(--magma-accent-on-emphasis));\n}\n```\n",
|
|
7811
|
+
"3. Mistakes": "Common incorrect uses of `<mds-chip>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Clickable Chip Without `clickable` or `selectable`\n\nWithout `clickable`, the chip has no `role`, no focus management, and no keyboard activation. Listening for click events on a static chip is a silent accessibility failure.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Apri\" variant=\"primary\" onclick=\"doSomething()\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Apri\" clickable variant=\"primary\"></mds-chip>\n<script>\n document.querySelector('mds-chip').addEventListener('mdsChipClickLabel', doSomething);\n</script>\n```\n\n#### Do Not Use `selected` Without `selectable`\n\n`selected` only has visual and semantic meaning when `selectable` is also set. On a non-selectable chip the attribute renders the selected style but the selection can never be toggled and no event fires, misleading users.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Attivo\" selected variant=\"success\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Attivo\" selectable selected variant=\"success\"></mds-chip>\n```\n\n#### Do Not Apply `tone` Values Outside the Minimal Ladder\n\n`mds-chip` accepts only `ToneMinimalVariantType`: `strong` and `weak`. Passing `outline`, `text`, or `box` is invalid: no style matches it, so the chip silently loses its variant colors.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Categoria\" tone=\"outline\" variant=\"primary\"></mds-chip>\n<mds-chip label=\"Categoria\" tone=\"text\" variant=\"primary\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Categoria\" tone=\"weak\" variant=\"primary\"></mds-chip>\n<mds-chip label=\"Categoria\" tone=\"strong\" variant=\"primary\"></mds-chip>\n```\n\n#### Do Not Slot Content Into the Chip\n\n`<mds-chip>` has no default or named slots - all content is driven by props (`label`, `icon`, `swatch`, `deletable`). Slotting HTML children is ignored by the Shadow DOM.\n\n```html\n<!-- INCORRECT -->\n<mds-chip>\n <span>Etichetta</span>\n <mds-icon name=\"mi/baseline/close\"></mds-icon>\n</mds-chip>\n\n<!-- CORRECT -->\n<mds-chip\n label=\"Etichetta\"\n icon=\"mi/baseline/pets\"\n deletable\n variant=\"primary\"\n></mds-chip>\n```\n\n#### Do Not Draw a Colour Through the Icon\n\nA circle icon painted with the colour, or the markup of an `<svg>` given to `icon`, sits on the disc of the icon, has no ring to keep a colour as light or as dark as the chip visible, and leans on custom properties that are not public. Give the colour to `swatch`.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"fireclay\" icon=\"mdi/circle\" style=\"--mds-chip-icon-color: #a89586\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"fireclay\" swatch=\"#a89586\"></mds-chip>\n```\n\n#### Do Not Say a State With a Swatch\n\nThe swatch draws its colour as given: a status painted there does not follow the mode, the named theme or the contrast preference as a variant does, and, hidden from assistive technologies, it adds nothing a screen reader hears. Say a status with `variant` and an icon; keep `swatch` for a colour the label names.\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Errore\" swatch=\"#d32f2f\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Errore\" icon=\"mi/baseline/error\" variant=\"error\" tone=\"strong\"></mds-chip>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Delete Button\n\nThe inner `mds-button` used for the delete affordance is a Shadow DOM implementation detail with no styling API of its own: targeting it with `>>>` or undocumented `::part()` names will break on minor releases. Restyle the chip and its leading icon through the public `--mds-chip-*` properties.\n\n```css\n/* INCORRECT */\nmds-chip >>> .button-delete {\n color: red;\n}\n\n/* CORRECT */\nmds-chip {\n --mds-chip-icon-background: rgb(var(--magma-danger-emphasis));\n}\n```\n\n#### Do Not Forget to Remove `await`-Pattern Analogue: Removing `selected` by Setting It to `false`\n\nWith `selected=\"false\"` the component reads the prop as `false` and drops the attribute when it renders, but until then the attribute is in the DOM and attribute selectors (`mds-chip[selected]`) match it. Remove the attribute; from JavaScript both `false` and `undefined` deselect the chip (the component turns `false` into `undefined` and drops the attribute).\n\n```html\n<!-- INCORRECT -->\n<mds-chip label=\"Filtro\" selectable selected=\"false\" variant=\"primary\"></mds-chip>\n\n<!-- CORRECT -->\n<mds-chip label=\"Filtro\" selectable variant=\"primary\"></mds-chip>\n```\n\n#### Do Not Use `<mds-chip>` as a Navigation Link\n\n`<mds-chip>` has no `href` prop. Wrapping it in an `<a>` creates a nested interactive element, breaks keyboard semantics, and fails accessibility audits. Use [`mds-button`](../mds-button/AGENTS.md) with `href` instead.\n\n```html\n<!-- INCORRECT -->\n<a href=\"/categoria/sport\">\n <mds-chip label=\"Sport\" variant=\"primary\"></mds-chip>\n</a>\n\n<!-- CORRECT -->\n<mds-button\n label=\"Sport\"\n href=\"/categoria/sport\"\n variant=\"primary\"\n tone=\"weak\"\n></mds-button>\n```\n"
|
|
7610
7812
|
},
|
|
7611
7813
|
"props": [
|
|
7612
7814
|
{
|
|
@@ -7800,6 +8002,37 @@
|
|
|
7800
8002
|
"getter": false,
|
|
7801
8003
|
"setter": false
|
|
7802
8004
|
},
|
|
8005
|
+
{
|
|
8006
|
+
"name": "swatch",
|
|
8007
|
+
"type": "string | undefined",
|
|
8008
|
+
"complexType": {
|
|
8009
|
+
"original": "string",
|
|
8010
|
+
"resolved": "string | undefined",
|
|
8011
|
+
"references": {}
|
|
8012
|
+
},
|
|
8013
|
+
"mutable": false,
|
|
8014
|
+
"attr": "swatch",
|
|
8015
|
+
"reflectToAttr": false,
|
|
8016
|
+
"docs": "A colour drawn as a round swatch where the icon goes, in place of `icon`: any CSS colour\n(`#2f6fd0`, `rgb(47 111 208)`, `oklch(55% 0.2 260)`). It is a value of the product, the\ncolour the label names (a family of colours, a category, a calendar), not a role of Magma:\nthe chip draws it as it is given in every mode and theme, inside a ring that keeps it visible\non the chip, at rest and selected. Decorative: hidden from assistive technologies, since the\nlabel names it. A value that is not a colour draws the empty ring.",
|
|
8017
|
+
"docsTags": [
|
|
8018
|
+
{
|
|
8019
|
+
"name": "example",
|
|
8020
|
+
"text": "'#2f6fd0'"
|
|
8021
|
+
}
|
|
8022
|
+
],
|
|
8023
|
+
"values": [
|
|
8024
|
+
{
|
|
8025
|
+
"type": "string"
|
|
8026
|
+
},
|
|
8027
|
+
{
|
|
8028
|
+
"type": "undefined"
|
|
8029
|
+
}
|
|
8030
|
+
],
|
|
8031
|
+
"optional": true,
|
|
8032
|
+
"required": false,
|
|
8033
|
+
"getter": false,
|
|
8034
|
+
"setter": false
|
|
8035
|
+
},
|
|
7803
8036
|
{
|
|
7804
8037
|
"name": "tone",
|
|
7805
8038
|
"type": "\"strong\" | \"weak\" | undefined",
|
|
@@ -8307,7 +8540,7 @@
|
|
|
8307
8540
|
"usage": {
|
|
8308
8541
|
"1. Description": "The `<mds-dropdown>` web component is a floating overlay surface of the Magma Design System that anchors arbitrary slotted content next to an external trigger element. It has no built-in trigger of its own: it attaches to a separate caller resolved via `target` and positions, flips and shifts itself around that element.\n\n#### Semantic Behavior\n\n- **Caller binding**: The dropdown does not render a trigger; it resolves its caller from the `target` selector and wires the chosen interaction onto that external element. Changing `target` re-binds the caller.\n- **Visibility is the single source of truth**: The `visible` prop drives the whole lifecycle - it positions the floating element, optionally shows the backdrop, and emits the events; setting it back to `false` dismisses it.\n- **Outside-click dismissal**: While open, clicking outside both the host and the caller closes the dropdown.\n- **Escape to close**: Pressing Escape hides the dropdown, and hands the focus back to the caller when the panel was holding it.\n- **Keyboard, when the panel is a `menu`**: the arrows on the caller open the panel and land on the first entry (Up on the last), Enter does the same; inside the panel the arrows walk the entries and wrap at the ends, Home and End go to the first and to the last, Tab closes and lets the focus leave from the caller. A panel that declares another role is left alone: the arrows of a calendar or of a form belong to what the panel holds.\n- **Backdrop**: When `backdrop` is set, a backdrop is shown while the dropdown is visible and removed on close.\n- **Emitted events**: `mdsDropdownChange` fires on every visibility transition; `mdsDropdownVisible` and `mdsDropdownHide` fire on open and close respectively. Each detail carries the resolved `caller` and the current `visible` state.\n- **Default slot is the panel content**: Anything in the default slot (text, HTML, or other components) is the surface shown when the dropdown is triggered.\n- **ARIA wiring**: The panel declares itself a `menu` and names the elements the slot receives as its entries (`role=\"menuitem\"`, a role of their own other than `button` being left alone); the caller receives `aria-haspopup`, an `aria-controls` pointing at the panel and an `aria-expanded` that follows `visible`. A panel that is not a list of actions declares its own `role` in the markup and keeps it, its contents then being left alone. A caller that exposes no role of its own - a generic host that keeps its control inside its shadow root, such as `mds-tab-item` - is left unwired, none of those attributes being valid on it.\n\n#### Properties & Visual Configurations\n\n- **`interaction`** decides how the caller opens the panel: `'click'` toggles on caller click (with outside-click and Escape dismissal), `'mouseover'` opens on hover and closes on mouse leave, and `'none'` wires nothing on the caller, so visibility is controlled programmatically through `visible` (an open panel still closes on outside click and Escape).\n- **`target`** (required) is the CSS selector of the external element the dropdown attaches to and positions against.\n\n#### Other behavioral props\n\n- **`placement`** sets the side relative to the caller, taken whenever it has room: by default (auto-placement) the panel moves to the opposite side, then to the sides across, only when it does not fit there. **`disableAutoPlacement`** pins it to `placement`, and **`flip`** then allows the fallback to the opposite side only. The panel is shifted to stay inside the viewport with a safe margin by default - **`disableShift`** opts out of this and **`shiftPadding`** tunes the margin.\n- **`offset`** controls the gap between the panel and the caller; the pointer toward the caller is shown by default (**`hideArrow`** removes it) and **`arrowPadding`** insets it from the panel edges.\n- the panel tracks the caller smoothly as the page scrolls by default (**`disableSmooth`** opts out); **`strategy`** chooses the CSS positioning mode (`'absolute'` vs `'fixed'`) and **`zIndex`** sets the stacking order.\n",
|
|
8309
8542
|
"2. Examples": "Correct and idiomatic ways to use the `<mds-dropdown>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Dropdown Menu\n\nThe minimal required setup: a trigger element with a unique `id` and a `<mds-dropdown>` with `target` pointing at it. The dropdown binds to the caller on `click` by default and dismisses on outside-click or Escape.\n\n```html\n<mds-button id=\"menu-utente\" label=\"Profilo\" icon=\"mi/baseline/account-circle\" variant=\"primary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#menu-utente\">\n <mds-button icon=\"mi/baseline/settings\" variant=\"dark\" tone=\"text\" label=\"Impostazioni account\"></mds-button>\n <mds-button icon=\"mi/baseline/logout\" variant=\"error\" tone=\"text\" label=\"Esci\"></mds-button>\n</mds-dropdown>\n```\n\n#### Panel That Is Not a Menu\n\nThe dropdown is a `menu` by default, a list of actions being what it holds most of the time. A panel that holds anything else - a calendar, a form, a paragraph with a link - declares its own `role`, which the component never overwrites: its contents are then left alone instead of being named entries of a menu.\n\n```html\n<mds-button id=\"info-policy\" label=\"Come usiamo i tuoi dati\" variant=\"primary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#info-policy\" role=\"group\">\n <mds-text typography=\"tip\">I dati restano sui server di Maggioli.</mds-text>\n <mds-button href=\"/policy\" label=\"Leggi la policy\" variant=\"dark\" tone=\"text\" size=\"sm\"></mds-button>\n</mds-dropdown>\n```\n\n#### Dropdown with Arrow Pointer\n\nThe arrow pointer is shown by default to visually connect the panel to its caller; add `hide-arrow` to remove it. Adjust `arrow-padding` when the panel is narrow and the arrow would clip the rounded corners.\n\n```html\n<mds-button id=\"aiuto-contestuale\" label=\"Aiuto\" icon=\"mi/baseline/help-outline\" variant=\"primary\" tone=\"outline\"></mds-button>\n\n<mds-dropdown target=\"#aiuto-contestuale\" arrow-padding=\"16\">\n <mds-text typography=\"h6\">Come funziona?</mds-text>\n <mds-text typography=\"detail\">Seleziona un campo per vedere la guida contestuale.</mds-text>\n</mds-dropdown>\n```\n\n#### Dropdown with Backdrop\n\nUse `backdrop` to dim the rest of the page while the panel is open. This is appropriate for panels with a higher modal weight, such as user-account menus or multi-step pickers.\n\nThe backdrop is appended to `<body>`, out of reach of the CSS inheritance of the dropdown: when it opens, the dropdown hands it the value it resolves for `--mds-dropdown-backdrop-z-index` and its fade duration, by default the ones of the page backdrop (`--magma-backdrop-z-index`, `--magma-backdrop-animation-duration`). With the animation preference set to reduce, the backdrop appears and goes without a fade.\n\n```html\n<mds-button id=\"selezione-filtri\" label=\"Filtra risultati\" icon=\"mi/baseline/filter-list\" variant=\"primary\"></mds-button>\n\n<mds-dropdown target=\"#selezione-filtri\" backdrop>\n <mds-text typography=\"h6\">Filtra per categoria</mds-text>\n <mds-filter>\n <mds-filter-item label=\"Documenti\"></mds-filter-item>\n <mds-filter-item label=\"Immagini\"></mds-filter-item>\n <mds-filter-item label=\"Video\"></mds-filter-item>\n </mds-filter>\n</mds-dropdown>\n```\n\n#### Mouseover Interaction\n\nSet `interaction=\"mouseover\"` for navigation mega-menus or info tooltips that should open on hover. The component adds a configurable delay (default 0.5 s, controlled by `--mds-dropdown-mouseover-delay`) before opening and closing.\n\n```html\n<mds-button id=\"info-progetto\" label=\"Dettagli progetto\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-dropdown target=\"#info-progetto\" interaction=\"mouseover\">\n <mds-entity icon=\"mi/baseline/folder\">\n <mds-text>Progetto Alfa - In corso</mds-text>\n </mds-entity>\n</mds-dropdown>\n```\n\n#### Programmatic Control via `visible`\n\nSet `interaction=\"none\"` to disable automatic wiring and drive visibility yourself. This is useful when the trigger logic lives in app code - for example, opening on a keyboard shortcut or a programmatic state change.\n\n```html\n<mds-button id=\"apri-manuale\" label=\"Apri pannello\" variant=\"primary\"></mds-button>\n\n<mds-dropdown id=\"pannello-opzioni\" target=\"#apri-manuale\" interaction=\"none\">\n <mds-text typography=\"detail\">Pannello gestito dal codice applicativo.</mds-text>\n</mds-dropdown>\n\n<script>\n const dropdown = document.querySelector('#pannello-opzioni');\n document.querySelector('#apri-manuale').addEventListener('click', () => {\n dropdown.visible = !dropdown.visible;\n });\n</script>\n```\n\n#### Placement and Auto-Placement\n\nUse `placement` to choose the side of the caller the panel opens on. Auto-placement is on by default: the panel takes `placement` whenever it has room there, and moves to the opposite side, then to the sides across, only when it does not fit; add `disable-auto-placement` to pin the panel strictly to `placement`.\n\n```html\n<!-- Pinned right-start placement (auto-placement disabled) -->\n<mds-button id=\"azioni-riga\" label=\"Azioni\" icon=\"mi/baseline/more-vert\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-dropdown target=\"#azioni-riga\" placement=\"right-start\" disable-auto-placement>\n <mds-button icon=\"mi/baseline/edit\" variant=\"dark\" tone=\"text\" label=\"Modifica\"></mds-button>\n <mds-button icon=\"mi/baseline/delete\" variant=\"error\" tone=\"text\" label=\"Elimina\"></mds-button>\n</mds-dropdown>\n\n<!-- Auto-placement (default) for constrained viewports -->\n<mds-button id=\"opzioni-voce\" label=\"Opzioni\" variant=\"primary\" tone=\"weak\"></mds-button>\n<mds-dropdown target=\"#opzioni-voce\">\n <mds-button label=\"Duplica\" icon=\"mi/baseline/content-copy\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-dropdown>\n```\n\n#### Flip and Shift for Viewport Safety\n\nEnable `flip` together with `disable-auto-placement` to let the pinned panel jump to the opposite side, and to no other, when there is not enough space in the preferred direction; auto-placement already includes that fallback. Shifting the panel to keep it inside the viewport is on by default; tune the safe margin with `shift-padding` (or set `disable-shift` to opt out).\n\n```html\n<mds-button id=\"btn-edge\" label=\"Vicino al bordo\" variant=\"primary\"></mds-button>\n\n<mds-dropdown target=\"#btn-edge\" placement=\"top\" disable-auto-placement flip shift-padding=\"16\">\n <mds-text typography=\"detail\">Questo pannello si sposta automaticamente se manca spazio.</mds-text>\n</mds-dropdown>\n```\n\n#### Listening to Visibility Events\n\nListen for `mdsDropdownVisible`, `mdsDropdownHide`, or `mdsDropdownChange` to react to open/close transitions. Each event detail contains `caller` (the resolved trigger element) and `visible` (the new state).\n\n```html\n<mds-button id=\"btn-notifica\" label=\"Notifiche\" icon=\"mi/baseline/notifications\" variant=\"primary\"></mds-button>\n\n<mds-dropdown id=\"pannello-notifiche\" target=\"#btn-notifica\">\n <mds-text typography=\"detail\">Nessuna nuova notifica.</mds-text>\n</mds-dropdown>\n\n<script>\n document.querySelector('#pannello-notifiche').addEventListener('mdsDropdownVisible', (e) => {\n console.log('Aperto. Trigger:', e.detail.caller);\n });\n document.querySelector('#pannello-notifiche').addEventListener('mdsDropdownHide', () => {\n console.log('Chiuso.');\n });\n</script>\n```\n\n#### Strategy `fixed` Inside Scrolling or Stacked Containers\n\nUse `strategy=\"fixed\"` when the dropdown is placed inside a scroll container, a sticky header, or a modal. With `strategy=\"absolute\"` (the default) the panel may be clipped by `overflow: hidden` ancestors.\n\n```html\n<!-- Inside a modal or a sticky nav - use fixed positioning -->\n<mds-button id=\"menu-header\" label=\"Menu\" variant=\"primary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#menu-header\" strategy=\"fixed\">\n <mds-button label=\"Pagina principale\" icon=\"mi/baseline/home\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Impostazioni\" icon=\"mi/baseline/settings\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-dropdown>\n```\n\n#### DOM Placement at the Document Root\n\nPlace `<mds-dropdown>` as a direct child of `<body>` (or as close as possible to the root) when the caller lives deep inside a stacking context. Nesting the dropdown inside the same transformed or `overflow: hidden` ancestor as the caller can break positioning and backdrop rendering.\n\n```html\n<body>\n <!-- Trigger lives inside a complex layout -->\n <div class=\"app-layout\">\n <nav>\n <mds-button id=\"btn-profilo\" label=\"Profilo\" variant=\"primary\"></mds-button>\n </nav>\n </div>\n\n <!-- Dropdown is a sibling of the layout root, not nested inside it -->\n <mds-dropdown target=\"#btn-profilo\" strategy=\"fixed\" backdrop>\n <mds-text typography=\"h6\">Mario Rossi</mds-text>\n <mds-button label=\"Esci\" icon=\"mi/baseline/logout\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-dropdown>\n</body>\n```\n\n#### Styling Customization\n\nCustomize the dropdown only through its public `--mds-dropdown-*` CSS custom properties. Use the semantic color roles via `rgb(var(--magma-<role>))` to preserve dark-mode, named-theme and high-contrast behavior.\n\n```css\n.my-context mds-dropdown {\n --mds-dropdown-background: rgb(var(--magma-surface-overlay));\n --mds-dropdown-mouseover-delay: 0.2s;\n --mds-dropdown-z-index: 5000;\n}\n```\n",
|
|
8310
|
-
"3. Mistakes": "Common incorrect uses of `<mds-dropdown>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Place the Dropdown Deep Inside a Scroll or Stacking Context\n\nNesting `<mds-dropdown>` inside a transformed, sticky, or `overflow: hidden` ancestor breaks floating positioning and backdrop rendering. Place it as close to `<body>` as the page structure allows, or switch to `strategy=\"fixed\"`.\n\n```html\n<!-- INCORRECT -->\n<div style=\"overflow: hidden; position: relative;\">\n <mds-button id=\"trigger\" label=\"Apri\" variant=\"primary\"></mds-button>\n <mds-dropdown target=\"#trigger\" backdrop>\n <mds-text>Contenuto</mds-text>\n </mds-dropdown>\n</div>\n\n<!-- CORRECT -->\n<div style=\"overflow: hidden; position: relative;\">\n <mds-button id=\"trigger\" label=\"Apri\" variant=\"primary\"></mds-button>\n</div>\n<mds-dropdown target=\"#trigger\" strategy=\"fixed\" backdrop>\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n```\n\n#### Do Not Use `visible=\"false\"` to Close the Dropdown\n\n`visible` is a boolean prop. The component reads the string `\"false\"` as `false` and drops the attribute when it renders, but until then the attribute is in the DOM and attribute selectors (`mds-dropdown[visible]`) match it. Remove the attribute or set the property to `false` in JavaScript to close it.\n\n```html\n<!-- INCORRECT -->\n<mds-dropdown target=\"#btn\" visible=\"false\">\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n\n<!-- CORRECT -->\n<mds-dropdown target=\"#btn\">\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n```\n\n```js\n// CORRECT - closing programmatically\ndocument.querySelector('mds-dropdown').visible = false;\n```\n\n#### Do Not Listen for Native `click` on the Target Instead of Dropdown Events\n\nThe dropdown manages its own interaction and emits `mdsDropdownVisible`, `mdsDropdownHide`, and `mdsDropdownChange`. Attaching a raw `click` listener to the caller can interfere with inside-click handling and may fire before the dropdown has updated its state.\n\n```html\n<!-- INCORRECT -->\n<mds-button id=\"btn-info\" label=\"Info\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#btn-info\">...</mds-dropdown>\n\n<script>\n // raw native event on the caller - races with dropdown internals\n document.querySelector('#btn-info').addEventListener('click', () => {\n console.log('cliccato');\n });\n</script>\n\n<!-- CORRECT -->\n<mds-button id=\"btn-info\" label=\"Info\" variant=\"primary\"></mds-button>\n<mds-dropdown id=\"dd-info\" target=\"#btn-info\">...</mds-dropdown>\n\n<script>\n document.querySelector('#dd-info').addEventListener('mdsDropdownVisible', (e) => {\n console.log('dropdown aperto', e.detail.visible);\n });\n</script>\n```\n\n#### Do Not Use `target` Without a Matching Element in the DOM\n\n`target` is resolved with `querySelector`
|
|
8543
|
+
"3. Mistakes": "Common incorrect uses of `<mds-dropdown>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Place the Dropdown Deep Inside a Scroll or Stacking Context\n\nNesting `<mds-dropdown>` inside a transformed, sticky, or `overflow: hidden` ancestor breaks floating positioning and backdrop rendering. Place it as close to `<body>` as the page structure allows, or switch to `strategy=\"fixed\"`.\n\n```html\n<!-- INCORRECT -->\n<div style=\"overflow: hidden; position: relative;\">\n <mds-button id=\"trigger\" label=\"Apri\" variant=\"primary\"></mds-button>\n <mds-dropdown target=\"#trigger\" backdrop>\n <mds-text>Contenuto</mds-text>\n </mds-dropdown>\n</div>\n\n<!-- CORRECT -->\n<div style=\"overflow: hidden; position: relative;\">\n <mds-button id=\"trigger\" label=\"Apri\" variant=\"primary\"></mds-button>\n</div>\n<mds-dropdown target=\"#trigger\" strategy=\"fixed\" backdrop>\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n```\n\n#### Do Not Use `visible=\"false\"` to Close the Dropdown\n\n`visible` is a boolean prop. The component reads the string `\"false\"` as `false` and drops the attribute when it renders, but until then the attribute is in the DOM and attribute selectors (`mds-dropdown[visible]`) match it. Remove the attribute or set the property to `false` in JavaScript to close it.\n\n```html\n<!-- INCORRECT -->\n<mds-dropdown target=\"#btn\" visible=\"false\">\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n\n<!-- CORRECT -->\n<mds-dropdown target=\"#btn\">\n <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n```\n\n```js\n// CORRECT - closing programmatically\ndocument.querySelector('mds-dropdown').visible = false;\n```\n\n#### Do Not Listen for Native `click` on the Target Instead of Dropdown Events\n\nThe dropdown manages its own interaction and emits `mdsDropdownVisible`, `mdsDropdownHide`, and `mdsDropdownChange`. Attaching a raw `click` listener to the caller can interfere with inside-click handling and may fire before the dropdown has updated its state.\n\n```html\n<!-- INCORRECT -->\n<mds-button id=\"btn-info\" label=\"Info\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#btn-info\">...</mds-dropdown>\n\n<script>\n // raw native event on the caller - races with dropdown internals\n document.querySelector('#btn-info').addEventListener('click', () => {\n console.log('cliccato');\n });\n</script>\n\n<!-- CORRECT -->\n<mds-button id=\"btn-info\" label=\"Info\" variant=\"primary\"></mds-button>\n<mds-dropdown id=\"dd-info\" target=\"#btn-info\">...</mds-dropdown>\n\n<script>\n document.querySelector('#dd-info').addEventListener('mdsDropdownVisible', (e) => {\n console.log('dropdown aperto', e.detail.visible);\n });\n</script>\n```\n\n#### Do Not Use `target` Without a Matching Element in the DOM\n\n`target` is resolved with `querySelector` when the dropdown loads, again whenever `target` changes, and when the dropdown comes back to the page after being moved. If the selector does not match any element the dropdown has no caller and cannot position or open itself. Always verify the `id` is present in the DOM before the component loads.\n\n```html\n<!-- INCORRECT - typo: button has id \"btn-salva\", target points to \"#salva\" -->\n<mds-button id=\"btn-salva\" label=\"Salva\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#salva\">\n <mds-text>Opzioni di salvataggio</mds-text>\n</mds-dropdown>\n\n<!-- CORRECT -->\n<mds-button id=\"btn-salva\" label=\"Salva\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#btn-salva\">\n <mds-text>Opzioni di salvataggio</mds-text>\n</mds-dropdown>\n```\n\n#### Do Not Use `<mds-button-dropdown>` and `<mds-dropdown>` Interchangeably\n\n[`mds-button-dropdown`](../mds-button-dropdown/AGENTS.md) is a compound component that already embeds a trigger button and a dropdown. Use it for a simple action-button-plus-menu. Use `<mds-dropdown>` directly only when the caller is not an `mds-button`, or when you need full control over the trigger element.\n\n```html\n<!-- INCORRECT - re-implementing what mds-button-dropdown already does -->\n<mds-button id=\"btn-azioni\" label=\"Azioni\" icon=\"mi/baseline/expand-more\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#btn-azioni\">\n <mds-button label=\"Modifica\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-dropdown>\n\n<!-- CORRECT - use the dedicated compound component -->\n<mds-button-dropdown label=\"Azioni\" variant=\"primary\">\n <mds-button label=\"Modifica\" variant=\"dark\" tone=\"text\"></mds-button>\n <mds-button label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Customize via Undocumented Shadow Internals\n\nThe supported customization surface is the public `--mds-dropdown-*` CSS custom properties. Targeting internal elements via `::part()` on non-documented parts, `>>>`, or class-name selectors couples your code to the Shadow DOM structure and breaks on any internal refactor.\n\n```css\n/* INCORRECT */\nmds-dropdown::part(panel) {\n border: 2px solid red;\n}\nmds-dropdown >>> .arrow {\n display: none;\n}\n\n/* CORRECT */\nmds-dropdown {\n --mds-dropdown-background: rgb(var(--magma-surface-overlay));\n --mds-dropdown-z-index: 6000;\n}\n```\n"
|
|
8311
8544
|
},
|
|
8312
8545
|
"props": [
|
|
8313
8546
|
{
|
|
@@ -11421,9 +11654,9 @@
|
|
|
11421
11654
|
}
|
|
11422
11655
|
],
|
|
11423
11656
|
"usage": {
|
|
11424
|
-
"1. Description": "The `<mds-filter-item>` web component is a single selectable option inside the [`<mds-filter>`](../mds-filter/AGENTS.md) container of the Magma Design System. It renders as a toggle button (icon, label, and an optional count badge) and acts as the toggleable unit that drives the parent's filter selection - it has no standalone HTML primitive equivalent.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-filter-item>` must be a direct slot child of `<mds-filter>`; it is not used standalone and should not be mixed with other child types.\n- **Self-toggling + event**: Clicking (or activating via the keyboard) flips `selected` and emits `mdsFilterItemSelect` with `{ id, selected }`. The `id` is the one set in the markup; an item without one gets `item-<index>` from the parent on load. The parent enforces single vs. multiple selection and re-emits `mdsFilterChange` with the aggregated value list.\n- **State owned with the parent**: `selected` doubles as a styling hook and as the flag the parent reads/writes - in single-select mode the parent clears the other items' selection, and on reset it clears the whole group. The parent also follows a `selected` set by the application, without emitting `mdsFilterChange`.\n- **Toggle button**: The host is a `button` whose `aria-pressed` follows `selected`. Its name is the `label` followed by the `count` as a number of results in the page language (the `lang` of `<html>`): \"Nuove, 11 results\" in English, \"Nuove, 11 risultati\" in Italian. An `aria-label` written on the host by the author stays.\n- **Keyboard activation**: Enter (and numpad Enter) and Space activate the item like a pointer click.\n- **Focus management**: The item is focusable unless `disabled`, in which case it drops out of the tab order.\n\n#### Properties & Visual Configurations\n\n- **`selected`**: The selection state of the item. Set it on initial markup to pre-select a filter, or at runtime from the application (a filter restored from the address, a clear button outside the bar): the parent follows, in single mode clearing the others.\n- **`value`**: The form/data value contributed to the parent's aggregated `mdsFilterChange` payload when the item is selected. Provide a meaningful value distinct from the human-readable `label`.\n- **`count`**: An optional badge showing how many results the filter would yield. Use it only when the count is meaningful to the user; omit it for purely categorical filters.\n- **`icon`**: Optional leading icon (an icon name string). Without a `label` the item is named after the last segment of the slug (`map` for `mi/baseline/map`); give it an `aria-label` of your own when the slug does not say what the filter does.\n- **`disabled`**: Blocks the item: it leaves the tab order, ignores clicks and keys, is announced as unavailable (`aria-disabled`) and is painted in the disabled text colour.\n",
|
|
11657
|
+
"1. Description": "The `<mds-filter-item>` web component is a single selectable option inside the [`<mds-filter>`](../mds-filter/AGENTS.md) container of the Magma Design System. It renders as a toggle button (icon, label, and an optional count badge) and acts as the toggleable unit that drives the parent's filter selection - it has no standalone HTML primitive equivalent.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-filter-item>` must be a direct slot child of `<mds-filter>`; it is not used standalone and should not be mixed with other child types.\n- **Self-toggling + event**: Clicking (or activating via the keyboard) flips `selected` and emits `mdsFilterItemSelect` with `{ id, selected }`. The `id` is the one set in the markup; an item without one gets `item-<index>` from the parent on load. The parent enforces single vs. multiple selection and re-emits `mdsFilterChange` with the aggregated value list.\n- **State owned with the parent**: `selected` doubles as a styling hook and as the flag the parent reads/writes - in single-select mode the parent clears the other items' selection, and on reset it clears the whole group. The parent also follows a `selected` set by the application, without emitting `mdsFilterChange`.\n- **Toggle button**: The host is a `button` whose `aria-pressed` follows `selected`. Its name is the `label` followed by the `count` as a number of results in the page language (the `lang` of `<html>`): \"Nuove, 11 results\" in English, \"Nuove, 11 risultati\" in Italian. The name contains the text the item shows, the label and the count as separate words, so a speech-input user can say what they see (WCAG 2.5.3, Label in Name). An `aria-label` written on the host by the author stays, as written: it must contain that text too, and follow the count when it changes.\n- **Keyboard activation**: Enter (and numpad Enter) and Space activate the item like a pointer click.\n- **Focus management**: The item is focusable unless `disabled`, in which case it drops out of the tab order.\n\n#### Properties & Visual Configurations\n\n- **`selected`**: The selection state of the item. Set it on initial markup to pre-select a filter, or at runtime from the application (a filter restored from the address, a clear button outside the bar): the parent follows, in single mode clearing the others.\n- **`value`**: The form/data value contributed to the parent's aggregated `mdsFilterChange` payload when the item is selected. Provide a meaningful value distinct from the human-readable `label`.\n- **`count`**: An optional badge showing how many results the filter would yield. Use it only when the count is meaningful to the user; omit it for purely categorical filters.\n- **`icon`**: Optional leading icon (an icon name string). Without a `label` the item is named after the last segment of the slug (`map` for `mi/baseline/map`); give it an `aria-label` of your own when the slug does not say what the filter does.\n- **`disabled`**: Blocks the item: it leaves the tab order, ignores clicks and keys, is announced as unavailable (`aria-disabled`) and is painted in the disabled text colour.\n",
|
|
11425
11658
|
"2. Examples": "Correct and idiomatic ways to use the `<mds-filter-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Filter Group\n\nThe canonical form. Place one or more `<mds-filter-item>` elements as direct children of `<mds-filter>`. Every item requires a `label` (the visible text) and a `value` (the machine-readable token emitted by the parent's `mdsFilterChange` event).\n\n```html\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n <mds-filter-item label=\"In attesa\" value=\"pending\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Pre-selecting an Item on Load\n\nSet `selected` on an item in the initial markup to make it active before any user interaction. The parent reads `selected` on mount and reflects the aggregated state correctly.\n\n```html\n<mds-filter label=\"Categoria\">\n <mds-filter-item label=\"Tutti\" value=\"all\" selected></mds-filter-item>\n <mds-filter-item label=\"Notizie\" value=\"news\"></mds-filter-item>\n <mds-filter-item label=\"Eventi\" value=\"events\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Count Badge\n\nPass a `count` string to show how many results each filter would yield. Use it when the number is meaningful to the user; omit it for purely categorical filters to keep the UI uncluttered.\n\n```html\n<mds-filter label=\"Priorita\">\n <mds-filter-item label=\"Alta\" value=\"high\" count=\"12\"></mds-filter-item>\n <mds-filter-item label=\"Media\" value=\"medium\" count=\"34\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\" value=\"low\" count=\"5\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Icon-Only Item\n\nOmit `label` and provide only `icon`. Without a label the item is named after the last segment of the icon slug (`grid view` for `mi/baseline/grid-view`); an `aria-label` of your own takes its place and stays. Use a recognizable icon so the purpose is clear without text, and give each item an `aria-label` when the slug does not say what it filters.\n\n```html\n<mds-filter label=\"Vista\">\n <mds-filter-item aria-label=\"Griglia\" icon=\"mi/baseline/grid-view\" value=\"grid\"></mds-filter-item>\n <mds-filter-item aria-label=\"Elenco\" icon=\"mi/baseline/view-list\" value=\"list\"></mds-filter-item>\n <mds-filter-item aria-label=\"Mappa\" icon=\"mi/baseline/map\" value=\"map\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Item with Icon and Label\n\nCombine `icon` and `label` for a filter item that pairs a glyph with a text description.\n\n```html\n<mds-filter label=\"Tipo documento\">\n <mds-filter-item icon=\"mi/baseline/picture-as-pdf\" label=\"PDF\" value=\"pdf\"></mds-filter-item>\n <mds-filter-item icon=\"mi/baseline/image\" label=\"Immagini\" value=\"image\"></mds-filter-item>\n <mds-filter-item icon=\"mi/baseline/video-library\" label=\"Video\" value=\"video\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Multiple Selection\n\nAdd `multiple` to `<mds-filter>` to allow several items to be selected at the same time. The parent aggregates the selected `value`s into a comma-separated string and emits it via `mdsFilterChange`.\n\n```html\n<mds-filter label=\"Settore\" multiple>\n <mds-filter-item label=\"Sanita\" value=\"health\"></mds-filter-item>\n <mds-filter-item label=\"Istruzione\" value=\"education\"></mds-filter-item>\n <mds-filter-item label=\"Trasporti\" value=\"transport\"></mds-filter-item>\n <mds-filter-item label=\"Ambiente\" value=\"environment\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Listening for Selection Events\n\nListen to `mdsFilterItemSelect` on a single item for per-item reactions, or to `mdsFilterChange` on the parent for the aggregated selection. The event detail for `mdsFilterItemSelect` is `{ id: string, selected: boolean }`.\n\n```html\n<mds-filter id=\"tipo-filter\" label=\"Tipo\">\n <mds-filter-item label=\"Bozza\" value=\"draft\"></mds-filter-item>\n <mds-filter-item label=\"Pubblicato\" value=\"published\"></mds-filter-item>\n</mds-filter>\n\n<script>\n document.getElementById('tipo-filter').addEventListener('mdsFilterChange', (e) => {\n console.log('Valori selezionati:', e.detail.value);\n });\n</script>\n```\n\n#### Reset Affordance\n\nAdd `reset` to `<mds-filter>` to show an automatic reset button when at least one item is active. The button is rendered by the parent internally - no extra `<mds-filter-item>` is needed - and named in the page language (\"Clear filters\").\n\n```html\n<mds-filter label=\"Regione\" reset>\n <mds-filter-item label=\"Nord\" value=\"north\"></mds-filter-item>\n <mds-filter-item label=\"Centro\" value=\"center\"></mds-filter-item>\n <mds-filter-item label=\"Sud\" value=\"south\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Styling the Count Badge\n\n`<mds-filter-item>` has no public CSS custom property and no shadow part: the count badge takes its colours from the item's `selected` state. To restyle the bar the items sit in, set the public `--mds-filter-*` properties on the parent `<mds-filter>`; use the semantic color roles via `rgb(var(--magma-<role>))`.\n\n```css\n.priority-filter mds-filter {\n --mds-filter-items-background: rgb(var(--magma-wash-strong));\n --mds-filter-items-background-active: rgb(var(--magma-accent-surface));\n}\n```\n",
|
|
11426
|
-
"3. Mistakes": "Common incorrect uses of `<mds-filter-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-filter-item>` Outside `<mds-filter>`\n\n`<mds-filter-item>` is a compound child component. Without its parent it has no selection management, no auto-scroll, and no `mdsFilterChange` aggregation. Always wrap it in `<mds-filter>`.\n\n```html\n<!-- INCORRECT -->\n<div class=\"my-filters\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</div>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Set `selected=\"false\"` to Deselect\n\n`selected` is a boolean prop: remove the attribute entirely to deselect, as for every boolean. The runtime happens to read the string `\"false\"` as `false`, but the attribute stays in the markup until the component renders, and HTML, `[selected]` selectors and `hasAttribute()` read a present attribute as set.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\" selected=\"false\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Omit `value`\n\n`value` is the machine-readable token the parent aggregates into `mdsFilterChange`. Without it the parent's event payload is empty or meaningless for consumers - always provide a distinct, meaningful value.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Priorita\">\n <mds-filter-item label=\"Alta\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Priorita\">\n <mds-filter-item label=\"Alta\" value=\"high\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\" value=\"low\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Slot Content Inside `<mds-filter-item>`\n\n`<mds-filter-item>` has no publicly documented default or named slots. Icon, label, and count are all props. Slotting arbitrary HTML has no effect - use the dedicated props instead.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Formato\">\n <mds-filter-item value=\"pdf\">\n <mds-icon name=\"mi/baseline/picture-as-pdf\"></mds-icon>\n PDF\n </mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Formato\">\n <mds-filter-item icon=\"mi/baseline/picture-as-pdf\" label=\"PDF\" value=\"pdf\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Listen for Native `click` Instead of `mdsFilterItemSelect`\n\nThe component handles its own toggle internally and emits `mdsFilterItemSelect` when selection changes. A native `click` listener added before the component has loaded runs before the internal toggle (listeners run in the order they were added), so it reads the old `selected` state.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n<script>\n document.querySelector('mds-filter-item[value=\"active\"]').addEventListener('click', (e) => {\n console.log('selected?', e.target.selected); // state not yet updated\n });\n</script>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n<script>\n document.querySelector('mds-filter-item[value=\"active\"]').addEventListener('mdsFilterItemSelect', (e) => {\n console.log('selected:', e.detail.selected);\n });\n</script>\n```\n\n#### Do Not Customize via Undocumented Shadow Parts or Internal Selectors\n\n`<mds-filter-item>` has no public CSS custom property and no shadow part: the count badge follows the `selected` state, and the bar is styled through the parent's public `--mds-filter-*` properties. Targeting shadow internals via `::part()`, `>>>`, or other selectors couples code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-filter-item >>> .count {\n border-radius: 4px;\n}\nmds-filter-item::part(count) {\n background: red;\n}\n\n/* CORRECT */\nmds-filter {\n --mds-filter-items-background: rgb(var(--magma-wash-strong));\n --mds-filter-items-background-active: rgb(var(--magma-accent-surface));\n}\n```\n"
|
|
11659
|
+
"3. Mistakes": "Common incorrect uses of `<mds-filter-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-filter-item>` Outside `<mds-filter>`\n\n`<mds-filter-item>` is a compound child component. Without its parent it has no selection management, no auto-scroll, and no `mdsFilterChange` aggregation. Always wrap it in `<mds-filter>`.\n\n```html\n<!-- INCORRECT -->\n<div class=\"my-filters\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</div>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n <mds-filter-item label=\"Archiviato\" value=\"archived\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Set `selected=\"false\"` to Deselect\n\n`selected` is a boolean prop: remove the attribute entirely to deselect, as for every boolean. The runtime happens to read the string `\"false\"` as `false`, but the attribute stays in the markup until the component renders, and HTML, `[selected]` selectors and `hasAttribute()` read a present attribute as set.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\" selected=\"false\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Omit `value`\n\n`value` is the machine-readable token the parent aggregates into `mdsFilterChange`. Without it the parent's event payload is empty or meaningless for consumers - always provide a distinct, meaningful value.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Priorita\">\n <mds-filter-item label=\"Alta\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Priorita\">\n <mds-filter-item label=\"Alta\" value=\"high\"></mds-filter-item>\n <mds-filter-item label=\"Bassa\" value=\"low\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Leave the Count Out of an `aria-label` of Your Own\n\nThe item names itself after its label and its count. An `aria-label` written on the host replaces that name as it is, and the count the item shows is visible text too: a name without it fails WCAG 2.5.3 (Label in Name), and a speech-input user saying the number does not reach the item. Put the count in the name, or leave the name to the item.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Vista\">\n <mds-filter-item aria-label=\"Vista a griglia\" icon=\"mi/baseline/grid-view\" value=\"grid\" count=\"3\"></mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Vista\">\n <mds-filter-item aria-label=\"Vista a griglia, 3 risultati\" icon=\"mi/baseline/grid-view\" value=\"grid\" count=\"3\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Slot Content Inside `<mds-filter-item>`\n\n`<mds-filter-item>` has no publicly documented default or named slots. Icon, label, and count are all props. Slotting arbitrary HTML has no effect - use the dedicated props instead.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Formato\">\n <mds-filter-item value=\"pdf\">\n <mds-icon name=\"mi/baseline/picture-as-pdf\"></mds-icon>\n PDF\n </mds-filter-item>\n</mds-filter>\n\n<!-- CORRECT -->\n<mds-filter label=\"Formato\">\n <mds-filter-item icon=\"mi/baseline/picture-as-pdf\" label=\"PDF\" value=\"pdf\"></mds-filter-item>\n</mds-filter>\n```\n\n#### Do Not Listen for Native `click` Instead of `mdsFilterItemSelect`\n\nThe component handles its own toggle internally and emits `mdsFilterItemSelect` when selection changes. A native `click` listener added before the component has loaded runs before the internal toggle (listeners run in the order they were added), so it reads the old `selected` state.\n\n```html\n<!-- INCORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n<script>\n document.querySelector('mds-filter-item[value=\"active\"]').addEventListener('click', (e) => {\n console.log('selected?', e.target.selected); // state not yet updated\n });\n</script>\n\n<!-- CORRECT -->\n<mds-filter label=\"Stato\">\n <mds-filter-item label=\"Attivo\" value=\"active\"></mds-filter-item>\n</mds-filter>\n<script>\n document.querySelector('mds-filter-item[value=\"active\"]').addEventListener('mdsFilterItemSelect', (e) => {\n console.log('selected:', e.detail.selected);\n });\n</script>\n```\n\n#### Do Not Customize via Undocumented Shadow Parts or Internal Selectors\n\n`<mds-filter-item>` has no public CSS custom property and no shadow part: the count badge follows the `selected` state, and the bar is styled through the parent's public `--mds-filter-*` properties. Targeting shadow internals via `::part()`, `>>>`, or other selectors couples code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-filter-item >>> .count {\n border-radius: 4px;\n}\nmds-filter-item::part(count) {\n background: red;\n}\n\n/* CORRECT */\nmds-filter {\n --mds-filter-items-background: rgb(var(--magma-wash-strong));\n --mds-filter-items-background-active: rgb(var(--magma-accent-surface));\n}\n```\n"
|
|
11427
11660
|
},
|
|
11428
11661
|
"props": [
|
|
11429
11662
|
{
|
|
@@ -12978,8 +13211,8 @@
|
|
|
12978
13211
|
}
|
|
12979
13212
|
],
|
|
12980
13213
|
"usage": {
|
|
12981
|
-
"1. Description": "The `<mds-icon>` web component is the single glyph primitive of the Magma Design System: it inlines an SVG into the DOM so the artwork inherits color and sizing from CSS, and it is the building block that nearly every other component (button, chip, input, banner, list-item, etc.) composes to render its iconography. It replaces a raw `<img>`/`<svg>` tag and centralizes how icon artwork is resolved.\n\n#### Semantic Behavior\n\n- **Decorative by default**: The icon contributes no accessible name; meaning must come from the surrounding labelled control or text.\n- **Source resolution**: `name` is interpreted three ways - a string starting with `data:image/svg+xml;base64,` is decoded inline (as UTF-8; a payload that is not base64 draws nothing and logs a console warning), a markup string starting with the `<svg` element, or with the XML declaration, doctype or comments a saved `.svg` file opens with, is used verbatim, and anything else is treated as an icon filename slug fetched as `<svg directory><slug>.svg` (a name starting with `http` is fetched as it is). Without a `name` (attribute missing or empty, property `undefined` or `null`) the icon renders nothing, sends no request and logs nothing; removing `name` clears the icon.\n- **Async load**: When `name` is a slug the icon paints once the SVG arrives; a failed fetch renders empty rather than throwing. Only the latest `name` and SVG path count: a request that finishes after a newer one is discarded.\n- **Path configuration**: The SVG directory is set programmatically via the shared `IconsSetService.setSvgPath()` singleton (imported from `@maggioli-design-system/magma
|
|
12982
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-icon>` component, ordered from most common to most specialized. The examples assume a working knowledge of the icon slug conventions documented in [`agents/conventions.md`](../../../../agents/conventions.md) and the icon setup in [`agents/assets.md`](../../../../agents/assets.md).\n\n#### Icon Slug from the Shared Library\n\nThe canonical form. Pass a slug string as `name`; the component fetches the matching SVG from the configured assets directory. Slugs follow the convention of the active iconsauce plugin: `mi/<variant>/<name>` for Material Icons, `mdi/<name>` for Material Design Icons, and `mgg/<name>` for the internal Maggioli set.\n\n```html\n<!-- Material Icons baseline variant -->\n<mds-icon name=\"mi/baseline/search\"></mds-icon>\n\n<!-- Material Design Icons -->\n<mds-icon name=\"mdi/alien\"></mds-icon>\n\n<!-- Internal Maggioli set -->\n<mds-icon name=\"mgg/action-email-send-wait\"></mds-icon>\n```\n\n#### Configuring the SVG Base Path via `IconsSetService` (recommended)\n\nImport the shared `IconsSetService` singleton from the package
|
|
13214
|
+
"1. Description": "The `<mds-icon>` web component is the single glyph primitive of the Magma Design System: it inlines an SVG into the DOM so the artwork inherits color and sizing from CSS, and it is the building block that nearly every other component (button, chip, input, banner, list-item, etc.) composes to render its iconography. It replaces a raw `<img>`/`<svg>` tag and centralizes how icon artwork is resolved.\n\n#### Semantic Behavior\n\n- **Decorative by default**: The icon contributes no accessible name; meaning must come from the surrounding labelled control or text.\n- **Source resolution**: `name` is interpreted three ways - a string starting with `data:image/svg+xml;base64,` is decoded inline (as UTF-8; a payload that is not base64 draws nothing and logs a console warning), a markup string starting with the `<svg` element, or with the XML declaration, doctype or comments a saved `.svg` file opens with, is used verbatim, and anything else is treated as an icon filename slug fetched as `<svg directory><slug>.svg` (a name starting with `http` is fetched as it is). Without a `name` (attribute missing or empty, property `undefined` or `null`) the icon renders nothing, sends no request and logs nothing; removing `name` clears the icon.\n- **Async load**: When `name` is a slug the icon paints once the SVG arrives; a failed fetch renders empty rather than throwing. Only the latest `name` and SVG path count: a request that finishes after a newer one is discarded.\n- **Path configuration**: The SVG directory is set programmatically via the shared `IconsSetService.setSvgPath()` singleton (imported from `@maggioli-design-system/magma`), with the `mdsIconSvgPath` `sessionStorage` key as an optional fallback and the `setSvgPath` instance method as an alternative; icons that mounted before the path was configured reload themselves once it is set. An icon removed from the page stops listening for path changes; once it is put back it picks up a path set in the meantime.\n\n#### Properties & Visual Configurations\n\n- **`name`** is the only configurable input and is overloaded: pass an icon filename slug to pull artwork from the shared library, a base64-encoded SVG `data:` URI for inline/dynamic artwork, or a full raw SVG string when the markup is generated at runtime.\n\nThis component does not use the shared `variant` / `tone` / `size` ladders defined in [`agents/variants.md`](../../../../agents/variants.md); the color comes from the inherited CSS `fill` and the size from the host `width` (24px by default, the height follows the square aspect ratio), which is how parent components tint and scale their icons.\n",
|
|
13215
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-icon>` component, ordered from most common to most specialized. The examples assume a working knowledge of the icon slug conventions documented in [`agents/conventions.md`](../../../../agents/conventions.md) and the icon setup in [`agents/assets.md`](../../../../agents/assets.md).\n\n#### Icon Slug from the Shared Library\n\nThe canonical form. Pass a slug string as `name`; the component fetches the matching SVG from the configured assets directory. Slugs follow the convention of the active iconsauce plugin: `mi/<variant>/<name>` for Material Icons, `mdi/<name>` for Material Design Icons, and `mgg/<name>` for the internal Maggioli set.\n\n```html\n<!-- Material Icons baseline variant -->\n<mds-icon name=\"mi/baseline/search\"></mds-icon>\n\n<!-- Material Design Icons -->\n<mds-icon name=\"mdi/alien\"></mds-icon>\n\n<!-- Internal Maggioli set -->\n<mds-icon name=\"mgg/action-email-send-wait\"></mds-icon>\n```\n\n#### Configuring the SVG Base Path via `IconsSetService` (recommended)\n\nImport the shared `IconsSetService` singleton from the package root, `@maggioli-design-system/magma` (`@maggioli-design-system/magma/services` is the same module), and call `setSvgPath()`. It updates the shared, in-memory icon path - kept on `globalThis` so every bundled copy of the service (lazy chunks, `esm`/`esm-es5` variants, `dist/components`) agrees on it - and notifies all mounted icons to (re)load immediately. **No `sessionStorage` is involved**, which makes it the safest option when storage is blocked (incognito, sandboxed iframes, storage partitioning). Pass an absolute path (starting with `/`) or a full URL. The icons are downloaded with `fetch`: under a Content Security Policy the origin of the path must be allowed by `connect-src` (or `default-src`), which `'self'` already does for a path on the page's own origin, while a CDN must be listed.\n\n```javascript\nimport { IconsSetService } from '@maggioli-design-system/magma';\n\nIconsSetService.setSvgPath('/assets/img/svg/');\n```\n\nIt can be called before or after the icons mount: instances mounted earlier re-fetch automatically once the path is set. A path set this way wins over the `mdsIconSvgPath` key of `sessionStorage`, read before or after it. On a server (no `window`) the call stores nothing: with SSR, call it in code the browser runs. Always use the exported `IconsSetService`; do not construct your own controller, which would keep a separate icon cache and listener list.\n\n#### Configuring the SVG Base Path via sessionStorage (optional)\n\nSet `mdsIconSvgPath` in `sessionStorage` before any `<mds-icon>` mounts; every icon instance falls back to this key when no path has been set programmatically. This one-liner is convenient but **may be blocked** by some browsers, privacy/incognito modes, storage partitioning, or sandboxed iframes - when that happens, use `IconsSetService.setSvgPath()` above instead.\n\n```javascript\nwindow.sessionStorage.setItem('mdsIconSvgPath', '/assets/img/svg/');\n```\n\n#### Forcing a Reload After Late Path Configuration\n\nIf icons are already in the DOM when the SVG path is set (for example, inside a lazy-loaded module), dispatch `mdsIconSvgPathUpdate` after configuring the path. Every mounted instance listens for this event and re-fetches.\n\n```javascript\nwindow.sessionStorage.setItem('mdsIconSvgPath', '/assets/img/svg/');\nwindow.dispatchEvent(new CustomEvent('mdsIconSvgPathUpdate'));\n```\n\n#### Configuring the SVG Base Path via the Instance Method\n\nAn alternative to `IconsSetService` when you already hold an `<mds-icon>` element: call its `setSvgPath` `@Method`. It delegates to the same singleton, so the effect is identical - prefer `IconsSetService` unless creating an element is more convenient (for example, in isolated testing environments).\n\n```javascript\nawait customElements.whenDefined('mds-icon');\nconst tmp = document.createElement('mds-icon');\ndocument.body.appendChild(tmp);\nif ('setSvgPath' in tmp) {\n tmp.setSvgPath('/assets/img/svg/');\n}\ndocument.body.removeChild(tmp);\n```\n\n#### Inline Raw SVG String\n\nPass a full SVG markup string as `name` when the artwork is generated or received at runtime and does not have a slug in the library. The component uses the string verbatim - no network request is made.\n\n```html\n<mds-icon\n name='<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path d=\"M12 2L2 22h20L12 2z\"/></svg>'\n></mds-icon>\n```\n\n#### Base64-encoded SVG Data URI\n\nPass a `data:image/svg+xml;base64,...` string when the icon is delivered from an API as a Base64 payload. The component decodes it inline, padding included - no external fetch occurs.\n\n```html\n<mds-icon name=\"data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTEyIDJMMiAyMmgyMHoiLz48L3N2Zz4=\"></mds-icon>\n```\n\n#### Sizing via CSS Width\n\n`<mds-icon>` is `display: inline-flex` with `aspect-ratio: 1` and a default width of `--spacing(600)`. Override size by setting a `width` on the host - height scales automatically via the aspect ratio. Use Magma spacing tokens to stay on-grid.\n\n```html\n<!-- Small icon using a Tailwind spacing utility -->\n<mds-icon name=\"mi/baseline/info\" class=\"w-400\"></mds-icon>\n\n<!-- Large icon -->\n<mds-icon name=\"mi/baseline/star\" class=\"w-1200\"></mds-icon>\n```\n\n#### Coloring via `fill` Utility or `currentColor`\n\nThe inlined SVG paints with the inherited CSS `fill`, so a Tailwind `fill-*` utility on the host, or `fill: currentColor` on a parent to follow its text color, is enough to tint the artwork; `color` alone does not tint it. Use Magma color roles, or a `label-*` colour for a category.\n\n```html\n<!-- Tint with a Magma label token -->\n<mds-icon name=\"mi/baseline/check-circle\" class=\"fill-label-green-06\"></mds-icon>\n\n<!-- Follow the current text color of a parent -->\n<p class=\"text-success-fg fill-current\">\n <mds-icon name=\"mi/baseline/check\"></mds-icon>\n Operazione completata\n</p>\n```\n\n#### Standalone Decorative Icon Inside a Labelled Control\n\n`<mds-icon>` renders with `aria-hidden=\"true\"` on its inner element; it carries no accessible name itself. When used standalone next to visible text, no extra ARIA is needed. When used as the only visual indicator inside an interactive control, the control must supply the accessible name.\n\n```html\n<!-- Decorative: the adjacent text provides the meaning -->\n<span class=\"flex items-center gap-200\">\n <mds-icon name=\"mi/baseline/email\"></mds-icon>\n Invia messaggio\n</span>\n```\n\n#### Styling via `::part(svg)`\n\nThe single documented shadow part is `svg` - the `<i>` wrapper around the inlined SVG. Use `::part(svg)` only for deep SVG styling not achievable through `fill` or `color`. Keep to documented parts; undocumented internals can change on minor releases.\n\n```css\nmds-icon::part(svg) {\n filter: drop-shadow(0 1px 2px rgb(var(--magma-shadow-ink) / 0.3));\n}\n```\n",
|
|
12983
13216
|
"3. Mistakes": "Common incorrect uses of `<mds-icon>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<img>` or Inline `<svg>` Instead of `<mds-icon>`\n\nUsing a raw `<img src=\"...svg\">` or a hardcoded `<svg>` literal bypasses the shared path management and cache (in memory and IndexedDB) and the shared theming surface. Use `<mds-icon name=\"...\">` with the slug so the icon is cached and takes its color from CSS.\n\n```html\n<!-- INCORRECT -->\n<img src=\"/assets/img/svg/mi/baseline/add.svg\" alt=\"\">\n<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path d=\"...\"/></svg>\n\n<!-- CORRECT -->\n<mds-icon name=\"mi/baseline/add\"></mds-icon>\n```\n\n#### Do Not Slot `<mds-icon>` to Add an Icon to Another Component\n\n`<mds-icon>` has no slot and accepts no children. Other Magma components expose an `icon` prop that renders the SVG through the shared service with correct positioning. Slotting `<mds-icon>` into the default slot of another component is stripped or misaligned.\n\n```html\n<!-- INCORRECT -->\n<mds-button>\n <mds-icon name=\"mi/baseline/add\"></mds-icon>\n Aggiungi\n</mds-button>\n\n<!-- CORRECT -->\n<mds-button label=\"Aggiungi\" icon=\"mi/baseline/add\" variant=\"primary\" tone=\"weak\"></mds-button>\n```\n\n#### Do Not Configure the Path with a Bare Relative Value\n\n`setSvgPath` (on `IconsSetService` or the element) treats an absolute path (starting with `/`) as relative to `window.location.origin`, and accepts full URLs. A bare relative value like `assets/svg/` is *accepted* but resolved against the **current page URL** (or the `<base href>`, when the page has one) on each request, so it silently breaks on nested routes (e.g. `/users/42/`). Always pass an absolute path or a full URL. Only an empty/whitespace value, or one that is not a URL (e.g. `http://`), throws (`Svg path not recognize ...`).\n\n```javascript\n// FRAGILE - resolved relative to the current page, breaks on nested routes\nIconsSetService.setSvgPath('assets/svg/');\n\n// CORRECT - absolute path (prefixed with the origin)\nIconsSetService.setSvgPath('/assets/svg/');\n\n// CORRECT - full URL (for example a CDN)\nIconsSetService.setSvgPath('https://cdn.example.com/svg/');\n```\n\n#### Do Not Rely on `<mds-icon>` for an Accessible Label\n\n`<mds-icon>` renders its inner element with `aria-hidden=\"true\"`. An icon used as the sole indicator inside an interactive control or next to no visible text provides no accessible name by itself. The surrounding control must carry the accessible name.\n\n```html\n<!-- INCORRECT - button has no accessible name -->\n<button>\n <mds-icon name=\"mi/baseline/delete\"></mds-icon>\n</button>\n\n<!-- CORRECT - use mds-button with aria-label -->\n<mds-button\n icon=\"mi/baseline/delete\"\n aria-label=\"Elimina elemento\"\n variant=\"error\"\n tone=\"text\"\n></mds-button>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the SVG\n\nThe only supported styling surface is `::part(svg)` and the inherited CSS `fill` set on the host. Using `>>>`, `/deep/`, or descendant selectors on `.icon` or internal class names couples code to the Shadow DOM structure and breaks on minor releases.\n\n```css\n/* INCORRECT */\nmds-icon >>> .icon svg path {\n fill: red;\n}\nmds-icon .icon {\n transform: rotate(45deg);\n}\n\n/* CORRECT */\nmds-icon {\n fill: rgb(var(--magma-danger-fg));\n}\nmds-icon::part(svg) {\n transform: rotate(45deg);\n}\n```\n\n#### Do Not Add `.svg` Extension to a Slug\n\nThe slug passed to `name` must not include the `.svg` extension - the service appends it when building the fetch URL. Adding the extension causes a double-`.svg` path (`mi/baseline/close.svg.svg`) that returns a 404.\n\n```html\n<!-- INCORRECT -->\n<mds-icon name=\"mi/baseline/close.svg\"></mds-icon>\n\n<!-- CORRECT -->\n<mds-icon name=\"mi/baseline/close\"></mds-icon>\n```\n\n#### Do Not Override Size with Fixed `width` and `height` HTML Attributes\n\n`<mds-icon>` is a custom element - HTML `width` and `height` attributes have no effect on it. Size is controlled by the CSS `width` property on the host (height follows from `aspect-ratio: 1`). Use a Tailwind width utility or a custom CSS rule.\n\n```html\n<!-- INCORRECT - attributes are ignored -->\n<mds-icon name=\"mi/baseline/star\" width=\"32\" height=\"32\"></mds-icon>\n\n<!-- CORRECT - CSS width drives the size -->\n<mds-icon name=\"mi/baseline/star\" class=\"w-1200\"></mds-icon>\n```\n"
|
|
12984
13217
|
},
|
|
12985
13218
|
"props": [
|
|
@@ -13647,6 +13880,10 @@
|
|
|
13647
13880
|
"readme": "# mds-input\n\n\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
|
|
13648
13881
|
"docs": "This is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.",
|
|
13649
13882
|
"docsTags": [
|
|
13883
|
+
{
|
|
13884
|
+
"name": "part",
|
|
13885
|
+
"text": "color-picker-button - Selects the button that opens the colour picker of a `color` field"
|
|
13886
|
+
},
|
|
13650
13887
|
{
|
|
13651
13888
|
"name": "part",
|
|
13652
13889
|
"text": "counter-button-decrease - Selects the button used to decrease the input value"
|
|
@@ -13693,9 +13930,9 @@
|
|
|
13693
13930
|
}
|
|
13694
13931
|
],
|
|
13695
13932
|
"usage": {
|
|
13696
|
-
"1. Description": "The `<mds-input>` web component is the primary single- and multi-line text entry control of the Magma Design System. It wraps a native `<input>` (or `<textarea>` when `type=\"textarea\"`) and layers on form association, validation, inline tips, iconography, password masking, numeric steppers, datalist suggestions and speech-to-text dictation.\n\n#### Semantic Behavior\n\n- **Form association**: The component reports its value to the surrounding `<form>`, so it submits natively. On `disabled` the reported value is cleared. A form reset brings back the value the field had at load, both shown and submitted, and drops the `'success'` or `'error'` look of a past blur, like a native input.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **Form validity**: The validators below also decide the validity reported to the form, on every change of the value or of the rules: like a native control, an invalid field matches `:invalid` and stops the submit, the browser shows a message in the page language next to the field and focuses it, and the field switches to `'error'` as on blur. Disabled and read-only fields are left out, and `novalidate` on the `<form>` turns the check off. `type=\"email\"` and `type=\"url\"` check the format of the value as a native input does.\n- **Validation on blur**: Validation runs when the field loses focus (and re-runs on input once invalid). A `required` field waits for that first blur too: until then, typing only updates its required tip. It drives the `variant` automatically to `'success'` or `'error'`, emits `mdsInputValidation` with the boolean result, and reverts to `'primary'` when an optional field is emptied.\n- **Type-aware validators**: The active validator set is derived from `type` - `email` and `url` install the format validators of the native types, `cf` the codice fiscale format and length validators, `isbn` a checksum validator, `piva` the partita IVA one (11 digits, the last one the check digit) and `cc` the card number one (13 to 19 digits, in groups split by spaces or dashes, that pass the Luhn check); no type applies an input mask, while `required`, `min`/`max` (any number, `0` included), `minlength`/`maxlength` and `pattern` add the corresponding constraint validators. As on a native input, `pattern` has to match the whole value, an expression that does not compile sets no rule, and `number`, `date`, `time` and `textarea` ignore it. The set is rebuilt whenever one of these props changes, also after load, as with the React wrappers under SSR: a pristine field only updates its required tip, a field already validated on blur is validated again. Custom validators can be attached at runtime through the `addValidator`/`removeValidator`/`hasValidator`/`getErrors` methods.\n- **Localized messages**: The messages of the built-in validators, the ones `getErrors()` returns and `mds-input-field` shows, are in the language of the page when the value is validated (`el`, `en`, `es`, `it`, English for any other).\n- **Error keys**: `getErrors()` reports each failed rule under its own key: `required`, `max`, `min`, `maxlength`, `minlength`, `pattern`, `email`, `url`, `piva`, `cc`, `isbn-error`, `cf-regex` and `cf-length`, plus the keys the custom validators return. Up to 2.5.0, `maxlength` and `minlength` were both reported as `minLenght`.\n- **Disabled / read-only tips**: `disabled` and `readonly` surface a persistent top tip describing the state; read-only fields also auto-select their text on focus.\n- **Character counter**: When `maxlength` is set a bottom counter tip shows `current / max` and shifts through fullness variants as the value approaches the limit. A `maxlength` of `0` or less is treated as unset.\n- **Password masking**: With `type=\"password\"` a toggle button reveals/hides the value; it is disabled with the field.\n- **Number steppers**: With `type=\"number\"` increment/decrement buttons are rendered; their placement follows `controlsLayout` and their glyphs follow `controlsIcon`. They are disabled on a disabled or read-only field, like the spin buttons of a native one.\n- **A fill a step off its surface**: on a page the field paints `surface-overlay`; inside a surface that paints `overlay` (the window of a dialog, `mds-banner`, `mds-status-bar`, `mds-dropdown`, `mds-table`) it paints `surface-default`, the step below, passed down as `--magma-field-fill`, so the field never melts into the window. `--mds-input-background` still sets the fill outright.\n- **Speech-to-text**: When `mic` is set a dictation button transcribes speech into the value, replacing what was there, and emits `mdsInputSpeechEnd` when the user stops the dictation; when the Web Speech API is unavailable the button switches to an error state and the value is left as it is. The dictation button is disabled on a disabled or read-only field, which the user cannot change, and a dictation in progress stops, emitting `mdsInputSpeechEnd`, when the field becomes so.\n- **Emitted events**: `mdsInputChange` carries the new value, `mdsInputKeydown` fires on every key pressed in the field with the native `KeyboardEvent` as detail (before the value changes: read the value from `mdsInputChange`), and `mdsInputFocus`/`mdsInputBlur` fire on focus transitions.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` ladder (color role) is defined in [`agents/variants.md`](../../../../agents/variants.md); `<mds-input>` consumes it for both intent styling and validation feedback, but does not expose a `tone` prop. It accepts `primary` (default), `ai`, `info`, `success`, `warning` and `error`.\n\n- **`type`** selects both the rendered control and the validation profile: it covers the native HTML types plus format types (`'cf'`, `'piva'`, `'isbn'`, `'cc'`) and switches the host to a multi-line `<textarea>` for `'textarea'`.\n- **`variant=\"ai\"`** auto-assigns the AI chatbot icon when no `icon` is otherwise provided, signposting AI-assisted fields.\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner icon, stepper buttons and password and microphone toggles scale with it. A `textarea` keeps its own height (`--mds-input-textarea-min-height`).\n\n#### Other behavioral props\n\n- **`icon`** is an SVG filename slug from the Magma icon library shown at the leading (left) edge of the field; it is suppressed while `await` is active, since the spinner takes its place.\n- **`controlsLayout`** chooses between stacked (`'vertical'`) and split (`'horizontal'`) stepper buttons, and **`controlsIcon`** picks arrow vs. plus/minus glyphs - both apply only to `type=\"number\"`.\n- **`datalist`** supplies suggestion options for `type=\"search\"` style autocompletion.\n- **`tip`** renders inline helper text below the field, and **`typography`** selects the field's text scale.\n",
|
|
13697
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-input>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Text Input\n\nThe simplest form: set `name` for form participation and `placeholder` for a visual hint. Wrap the component in [`mds-input-field`](../mds-input-field/AGENTS.md) to add a visible label and associated tip.\n\n```html\n<mds-input\n name=\"cognome\"\n placeholder=\"Inserisci il tuo cognome\"\n></mds-input>\n```\n\n#### Required Field with `tip` Helper Text\n\nUse `required` to validate that the field is not empty and `tip` to explain the constraint. The component surfaces a top-tip when focused and drives `variant` to `'error'` or `'success'` on blur. When the field collects the user's own data, set the matching `autocomplete` token (`email`, `given-name`, `tel`, ...) so browsers can identify its purpose (WCAG 2.1 SC 1.3.5) and offer autofill; without it the component default `autocomplete=\"off\"` applies.\n\n```html\n<mds-input\n name=\"email\"\n type=\"email\"\n autocomplete=\"email\"\n placeholder=\"nome@esempio.it\"\n required\n tip=\"Inserisci un indirizzo email valido\"\n></mds-input>\n```\n\n#### Textarea for Multi-line Content\n\nSet `type=\"textarea\"` to render a `<textarea>` instead of a single-line `<input>`. Use the `--mds-input-textarea-*` custom properties to control height and resize behaviour.\n\n```html\n<mds-input\n name=\"descrizione\"\n type=\"textarea\"\n placeholder=\"Descrivi il problema...\"\n maxlength=\"500\"\n></mds-input>\n```\n\n#### Character Counter via `maxlength`\n\nWhen `maxlength` is set the component renders a live `current / max` counter below the field. The counter shifts through fullness variants as the limit approaches. A value of `0` or less is treated as unset.\n\n```html\n<mds-input\n name=\"titolo\"\n placeholder=\"Titolo dell'articolo\"\n maxlength=\"120\"\n></mds-input>\n```\n\n#### Numeric Input with Steppers\n\nSet `type=\"number\"` to enable built-in increment/decrement buttons. Use `controlsLayout` to choose between stacked (`'vertical'`, default) and split (`'horizontal'`) placement, and `controlsIcon` to pick arrow vs. plus/minus glyphs. Use `min`, `max`, and `step` to constrain the legal range.\n\n```html\n<!-- Stacked (default) - arrow glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"1\"\n max=\"99\"\n step=\"1\"\n placeholder=\"1\"\n></mds-input>\n\n<!-- Horizontal split - arithmetic glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"0\"\n max=\"100\"\n controls-layout=\"horizontal\"\n controls-icon=\"arithmetic\"\n placeholder=\"0\"\n></mds-input>\n```\n\n#### Password Input\n\nSet `type=\"password\"` to render a masked field with a built-in visibility toggle. The component renders a custom dot-mask overlay and a show/hide button - no extra wiring is needed. Always set `autocomplete` to `new-password` (sign-up, password change) or `current-password` (login): the component default is `autocomplete=\"off\"`, which browsers and password managers ignore on credential fields, but the explicit token is what lets them pair the password with its username field and fill or generate the right value.\n\n```html\n<mds-input\n name=\"password\"\n type=\"password\"\n autocomplete=\"new-password\"\n placeholder=\"Scegli una password\"\n required\n></mds-input>\n```\n\n#### Login Form\n\nPair a username field carrying `autocomplete=\"username\"` with a password field carrying `autocomplete=\"current-password\"` inside a `<form>`, and submit through `<mds-button type=\"submit\">`. The native fields live in the Shadow DOM of each `<mds-input>`: among the password managers tested, Bitwarden, LastPass, Chrome and Edge detect and fill them, Firefox's built-in manager and KeePassXC-Browser do not (they only look at the light DOM).\n\n```html\n<form action=\"/login\" method=\"post\">\n <mds-input-field label=\"Email\">\n <mds-input name=\"username\" type=\"email\" autocomplete=\"username\" required></mds-input>\n </mds-input-field>\n <mds-input-field label=\"Password\">\n <mds-input name=\"password\" type=\"password\" autocomplete=\"current-password\" required></mds-input>\n </mds-input-field>\n\n <mds-button type=\"submit\" label=\"Accedi\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Italian-Specific Masked Types\n\n`type=\"cf\"` installs the codice fiscale format and length validators and `type=\"isbn\"` a checksum validator. `type=\"piva\"` accepts 11 digits whose last one is the check digit, without the `IT` prefix or spaces, and `type=\"cc\"` 13 to 19 digits, in groups split by spaces or dashes, that pass the Luhn check of card numbers. A value that breaks the format stops the submit of the form. No type applies a keyboard mask.\n\n```html\n<mds-input name=\"codice_fiscale\" type=\"cf\" placeholder=\"RSSMRA80A01H501Z\"></mds-input>\n<mds-input name=\"partita_iva\" type=\"piva\" placeholder=\"01234567890\"></mds-input>\n```\n\n#### Search Input with Datalist\n\nUse `type=\"search\"` combined with the `datalist` prop to offer autocomplete suggestions from a fixed list. The list is rendered inside the shadow DOM and wired automatically.\n\n```html\n<mds-input\n name=\"comune\"\n type=\"search\"\n placeholder=\"Cerca comune...\"\n></mds-input>\n```\n\n```javascript\n// Pass suggestions as a JavaScript array\ndocument.querySelector('mds-input').datalist = ['Roma', 'Milano', 'Napoli', 'Torino'];\n```\n\n#### Icon Decoration\n\nThe `icon` prop renders an SVG slug from the Magma icon library at the leading edge of the field. The icon is suppressed while `await` is active and the spinner takes its place.\n\n```html\n<mds-input\n name=\"cerca\"\n type=\"search\"\n icon=\"mi/baseline/search\"\n placeholder=\"Cerca...\"\n></mds-input>\n```\n\n#### AI-Assisted Field\n\nSet `variant=\"ai\"` to signal an AI-powered field. When no `icon` prop is present, the component auto-assigns the AI chatbot icon.\n\n```html\n<mds-input\n name=\"prompt\"\n type=\"text\"\n variant=\"ai\"\n placeholder=\"Chiedi qualcosa all'assistente...\"\n></mds-input>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while an async operation (e.g. a lookup) is in flight. The component renders an inline spinner in place of the icon. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-input name=\"codice\" placeholder=\"Verifica in corso...\" await></mds-input>\n```\n\n#### Speech-to-Text Dictation\n\nSet the `mic` boolean attribute to render a dictation button. Starting a dictation clears the current value and writes the recognized speech in its place; the component emits `mdsInputSpeechEnd` when the user stops the dictation. If the Web Speech API is unavailable the button switches to an error state and the value is kept.\n\n```html\n<mds-input\n name=\"note_vocali\"\n type=\"text\"\n mic\n placeholder=\"Parla o scrivi...\"\n></mds-input>\n```\n\n#### Listening to Events\n\nListen for `mdsInputChange` instead of native `input` or `change`: `change` does not cross the shadow boundary, and `input` reports only typing, not the values set by the steppers, the dictation or a script.\n\n```javascript\ndocument.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {\n console.log(e.detail.value);\n});\n\ndocument.querySelector('mds-input').addEventListener('mdsInputValidation', (e) => {\n console.log('valido:', e.detail);\n});\n```\n\n#### Form Participation\n\n`<mds-input>` is form-associated. It submits natively inside a `<form>`; set `name` so the value is included in form data. Its validation is reported to the form too: an empty `required` field, or one that breaks another rule, stops the submit like a native input and shows the error. Add `novalidate` to the `<form>` when your own code validates on submit. A reset brings every field back to its value at load and to its pristine look.\n\n```html\n<form action=\"/salva\" method=\"post\">\n <mds-input name=\"nome\" type=\"text\" placeholder=\"Nome\" required></mds-input>\n <mds-input name=\"cognome\" type=\"text\" placeholder=\"Cognome\" required></mds-input>\n <mds-input name=\"email\" type=\"email\" placeholder=\"Email\" required></mds-input>\n\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n</form>\n```\n\n#### Read-Only Display\n\nUse `readonly` when the value should be visible but not editable. A persistent top tip describes the state, and the field text is auto-selected on focus for easy copying.\n\n```html\n<mds-input\n name=\"codice_riferimento\"\n value=\"REF-2024-00123\"\n readonly\n></mds-input>\n```\n\n#### Styling Customization\n\nStyle the input only through its public `--mds-input-*` CSS custom properties. Set them on the host or a parent selector. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.search-bar mds-input {\n --mds-input-background: rgb(var(--magma-wash-base));\n}\n\n/* Textarea: fixed height, allow resize */\n.notes-area mds-input {\n --mds-input-textarea-min-height: 8rem;\n --mds-input-textarea-max-height: 24rem;\n --mds-input-textarea-resize: vertical;\n}\n```\n\n#### Sizing a Field to the Controls Next to It\n\nGive the fields of a row the `size` of the buttons beside them, so they share one height: `sm` 28px, `md` 36px, `lg` 48px (default), the sizes of [`<mds-button>`](../mds-button/AGENTS.md). `<mds-input-select>`, `<mds-input-date>` and `<mds-input-date-range>` take the same values.\n\n```html\n<div class=\"flex items-center gap-200\">\n <mds-input size=\"md\" type=\"search\" icon=\"mi/baseline/search\" placeholder=\"Cerca\"></mds-input>\n <mds-input-select size=\"md\" placeholder=\"Stato\">\n <option value=\"open\">Aperte</option>\n <option value=\"closed\">Chiuse</option>\n </mds-input-select>\n <mds-button size=\"md\" label=\"Filtra\"></mds-button>\n</div>\n```\n\n",
|
|
13698
|
-
"3. Mistakes": "Common incorrect uses of `<mds-input>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Raw `<input>` When `<mds-input>` Exists\n\nReaching for a plain `<input>` bypasses theming, validation, tips, accessible state announcements, and form-reset behavior provided by the component.\n\n```html\n<!-- INCORRECT -->\n<input type=\"text\" name=\"nome\" placeholder=\"Nome\" class=\"my-input\">\n\n<!-- CORRECT -->\n<mds-input name=\"nome\" type=\"text\" placeholder=\"Nome\"></mds-input>\n```\n\n#### Do Not Set Boolean Attributes to the String `\"false\"`\n\n`disabled`, `required`, `readonly`, `mic` and `await` are boolean attributes: remove the attribute entirely to turn it off. `mds-input` is form-associated, so as on a native control any value turns them on, `\"false\"` included: this markup renders a disabled, required field.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"note\" disabled=\"false\" required=\"false\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input name=\"note\"></mds-input>\n```\n\n#### Do Not Force `variant` for Validation Feedback\n\nThe component drives `variant` to `'success'` or `'error'` automatically on blur when validators are active. Setting `variant` manually overrides the feedback and breaks the visual contract.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"codice\" variant=\"error\" tip=\"Valore non valido\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input name=\"codice\" required tip=\"Inserisci un valore valido\"></mds-input>\n```\n\n#### Do Not Listen to Native `input` or `change` Events\n\nThe native `change` event does not cross the shadow boundary, and `input` reports only typing, not the values set by the steppers, the dictation or a script. Use the documented `mdsInputChange` event instead, which fires for every value change.\n\n```javascript\n// INCORRECT\ndocument.querySelector('mds-input').addEventListener('input', (e) => {\n console.log(e.target.value);\n});\n\n// CORRECT\ndocument.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {\n console.log(e.detail.value);\n});\n```\n\n#### Do Not Use `type=\"number\"` Native Browser Spinners and Then Override the Input\n\nThe component renders its own increment/decrement buttons and hides the native browser spinners. Do not try to re-enable them via CSS, and do not add inline JS `stepUp`/`stepDown` calls - use the `controlsLayout` and `controlsIcon` props to configure the built-in controls.\n\n```html\n<!-- INCORRECT -->\n<mds-input type=\"number\" style=\"-moz-appearance: auto;\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input\n type=\"number\"\n controls-layout=\"horizontal\"\n controls-icon=\"arithmetic\"\n min=\"0\"\n max=\"100\"\n></mds-input>\n```\n\n#### Do Not Use a Legacy or Invalid `type` Value\n\n`<mds-input>` accepts a specific set of `type` values: `text`, `email`, `number`, `password`, `search`, `tel`, `url`, `date`, `time`, `textarea`, `cf`, `piva`, `cc`, `isbn`. Supplying anything else (e.g. `\"checkbox\"`, `\"radio\"`, `\"file\"`) is passed straight to the inner native `<input>`, which renders a bare native control that the component neither styles nor reports correctly to the form. Use the dedicated Magma component for those controls.\n\n```html\n<!-- INCORRECT -->\n<mds-input type=\"checkbox\" name=\"accetto\"></mds-input>\n<mds-input type=\"file\" name=\"allegato\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input-switch name=\"accetto\"></mds-input-switch>\n<mds-input-upload name=\"allegato\"></mds-input-upload>\n```\n\n#### Do Not Use `placeholder` as the Accessible Label\n\n`placeholder` disappears on input and is never read as a label by assistive tech. Always pair `<mds-input>` with [`mds-input-field`](../mds-input-field/AGENTS.md) (which shows a visible label and passes it down as the accessible name) or supply `aria-label` directly on the host.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"ricerca\" placeholder=\"Cerca per nome\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input-field label=\"Cerca per nome\">\n <mds-input name=\"ricerca\" placeholder=\"Cerca per nome\"></mds-input>\n</mds-input-field>\n```\n\n#### Do Not Pierce the Shadow DOM to Style Internal Parts\n\nThe supported customization surface is the public `--mds-input-*` CSS custom properties plus the documented shadow parts (`field`, `tip-top`, `tip-bottom`, `tip-count`, `password-toggle-button`, `counter-button-increase`, `counter-button-decrease`, `mic-toggle-button`). Targeting undocumented internals via `>>>` or arbitrary class names couples your code to the Shadow DOM implementation.\n\n```css\n/* INCORRECT */\nmds-input >>> .input {\n border: 2px solid red;\n}\n\n/* CORRECT */\nmds-input {\n --mds-input-ring: 0 0 0 2px rgb(var(--magma-danger-border));\n --mds-input-background: rgb(var(--magma-danger-wash-base));\n}\nmds-input::part(field) {\n font-style: italic;\n}\n```\n"
|
|
13933
|
+
"1. Description": "The `<mds-input>` web component is the primary single- and multi-line text entry control of the Magma Design System. It wraps a native `<input>` (or `<textarea>` when `type=\"textarea\"`) and layers on form association, validation, inline tips, iconography, password masking, numeric steppers, colour codes with a swatch and the picker of the platform, datalist suggestions and speech-to-text dictation.\n\n#### Semantic Behavior\n\n- **Form association**: The component reports its value to the surrounding `<form>`, so it submits natively. On `disabled` the reported value is cleared. A form reset brings back the value the field had at load, both shown and submitted, and drops the `'success'` or `'error'` look of a past blur, like a native input.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **Form validity**: The validators below also decide the validity reported to the form, on every change of the value or of the rules: like a native control, an invalid field matches `:invalid` and stops the submit, the browser shows a message in the page language next to the field and focuses it, and the field switches to `'error'` as on blur. Disabled and read-only fields are left out, and `novalidate` on the `<form>` turns the check off. `type=\"email\"` and `type=\"url\"` check the format of the value as a native input does.\n- **Validation on blur**: Validation runs when the field loses focus (and re-runs on input once invalid). A `required` field waits for that first blur too: until then, typing only updates its required tip. It drives the `variant` automatically to `'success'` or `'error'`, emits `mdsInputValidation` with the boolean result, and reverts to `'primary'` when an optional field is emptied.\n- **Type-aware validators**: The active validator set is derived from `type` - `email` and `url` install the format validators of the native types, `cf` the codice fiscale format and length validators, `isbn` a checksum validator, `piva` the partita IVA one (11 digits, the last one the check digit) and `cc` the card number one (13 to 19 digits, in groups split by spaces or dashes, that pass the Luhn check) and `color` the colour code one (see Colour field); no type applies an input mask, while `required`, `min`/`max` (any number, `0` included), `minlength`/`maxlength` and `pattern` add the corresponding constraint validators. As on a native input, `pattern` has to match the whole value, an expression that does not compile sets no rule, and `number`, `date`, `time`, `textarea` and `color` ignore it. The set is rebuilt whenever one of these props changes, also after load, as with the React wrappers under SSR: a pristine field only updates its required tip, a field already validated on blur is validated again. Custom validators can be attached at runtime through the `addValidator`/`removeValidator`/`hasValidator`/`getErrors` methods.\n- **Localized messages**: The messages of the built-in validators, the ones `getErrors()` returns and `mds-input-field` shows, are in the language of the page when the value is validated (`el`, `en`, `es`, `it`, English for any other).\n- **Error keys**: `getErrors()` reports each failed rule under its own key: `required`, `max`, `min`, `maxlength`, `minlength`, `pattern`, `email`, `url`, `piva`, `cc`, `color`, `isbn-error`, `cf-regex` and `cf-length`, plus the keys the custom validators return. Up to 2.5.0, `maxlength` and `minlength` were both reported as `minLenght`.\n- **Disabled / read-only tips**: `disabled` and `readonly` surface a persistent top tip describing the state; read-only fields also auto-select their text on focus. The top tip (this badge, and the dot of `required`) stands on the top border of the field, half outside, clear of its rounded corner by its radius plus a margin, and stays there while the field has the focus: inside the field it covered the button at its end.\n- **No action that changes the value on a field the user cannot change**: a read-only or disabled field (a disabled `<fieldset>` included) has none of the buttons at its end that change the value (the steppers of a number, the dictation button, the picker of a colour); its text takes their room and its end is left to the badge of its state. The password toggle stays, since it shows the value without changing it (disabled with the field).\n- **Character counter**: When `maxlength` is set a bottom counter tip shows `current / max` and shifts through fullness variants as the value approaches the limit. A `maxlength` of `0` or less is treated as unset.\n- **Password masking**: With `type=\"password\"` a toggle button reveals/hides the value; it is disabled with the field.\n- **Colour field**: `type=\"color\"` keeps a text field, where a colour code is typed and validated, with a swatch of the colour at its start and a button at its end that opens the colour picker of the platform; it keeps the sizes, the variants, `readonly`, `required`, the form and the validation, and the label and message of `mds-input-field`. The value, in `mdsInputChange` and in the form, is the colour as `#rrggbb` in lower case, the valid lowercase simple colour of HTML, without alpha. The text also takes `#rgb` and the code without `#`, in upper or lower case (what Figma copies), and the field writes it back as `#rrggbb` when it is left. Any other text, a name or `rgb()` among them, is an error under the key `color` whose message says what to write: the text stays for the user to correct and the value becomes `''`, as a native number input does with a text that is no number (the form gets `''` and the field reports `badInput`), so the event and the form only ever carry a colour or `''`. A value set by code is read the same way: `#ABC` becomes `#aabbcc`, `red` is shown with its error and the value becomes `''`. A field that is not `required` can stay empty, where a native colour input always holds `#000000`.\n- **The swatch and the picker button**: the swatch is a disc of the colour of the value, as large as the glyph of an icon and where the icon goes, so it scales with `size`; while the text names no colour it is empty, its ring alone. The ring is the `border-strong` role, the 3:1 contrast a graphic needs on the fill of the field to show a white or a black colour. The button at the end, where the microphone of a text field goes, has a palette icon and the name \"Choose a colour for\" the name of the field in the page language, and comes after the text in the order of the keyboard: it opens the colour picker of the platform (a native `<input type=\"color\">` hidden under it) on the colour of the value, black for an empty field; the colour picked writes the text and the value and emits `mdsInputChange` as typing does. A click on the swatch opens it too, a shortcut for the pointer: the swatch is hidden from assistive technologies and out of the order of the keyboard, the button is the control. A read-only or disabled field (a disabled `<fieldset>` included) has no button: it offers no way to change the value, the swatch still shows the colour and opens nothing, and the end of the field is left to the badge of its state. Next to the other props: the swatch takes the place of `icon`, which a colour field ignores (one mark at the start, as on `mds-chip`), with the icon `variant=\"ai\"` adds; `await` leaves the swatch, which shows the value, and puts its spinner at the end, before the button (at the very end of a read-only or disabled field); `mic` is ignored, since a colour code is typed or picked, not dictated, and the end holds the button.\n- **Number steppers**: With `type=\"number\"` increment/decrement buttons are rendered; their placement follows `controlsLayout` and their glyphs follow `controlsIcon`. The side buttons of the horizontal layout are as tall as the field, with the icon of an `sm` button at `md` and `sm`, as the other buttons inside the field. A read-only or disabled number has no steppers: it is a plain field, with the padding of any field and its text at the start (the centring of the horizontal layout belongs to the buttons on its sides). The arrow keys still step the value of a field the user can change.\n- **A fill a step off its surface**: on a page the field paints `surface-overlay`; inside a surface that paints `overlay` (the window of a dialog, `mds-banner`, `mds-status-bar`, `mds-dropdown`, `mds-table`) it paints `surface-default`, the step below, passed down as `--magma-field-fill`, so the field never melts into the window. `--mds-input-background` still sets the fill outright.\n- **Speech-to-text**: When `mic` is set a dictation button transcribes speech into the value, replacing what was there, and emits `mdsInputSpeechEnd` when the user stops the dictation; when the Web Speech API is unavailable the button switches to an error state and the value is left as it is. A disabled or read-only field (a disabled `<fieldset>` included), which the user cannot change, has no dictation button, and leaves the end of the field to the badge of its state; a dictation in progress stops at once, emitting `mdsInputSpeechEnd`, when the field becomes so.\n- **Emitted events**: `mdsInputChange` carries the new value, `mdsInputKeydown` fires on every key pressed in the field with the native `KeyboardEvent` as detail (before the value changes: read the value from `mdsInputChange`), and `mdsInputFocus`/`mdsInputBlur` fire on focus transitions.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` ladder (color role) is defined in [`agents/variants.md`](../../../../agents/variants.md); `<mds-input>` consumes it for both intent styling and validation feedback, but does not expose a `tone` prop. It accepts `primary` (default), `ai`, `info`, `success`, `warning` and `error`.\n\n- **`type`** selects both the rendered control and the validation profile: it covers the native HTML types (`color` as a text field with a swatch and a picker button, see Colour field) plus format types (`'cf'`, `'piva'`, `'isbn'`, `'cc'`) and switches the host to a multi-line `<textarea>` for `'textarea'`.\n- **`variant=\"ai\"`** auto-assigns the AI chatbot icon when no `icon` is otherwise provided, signposting AI-assisted fields.\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner icon, stepper buttons and password and microphone toggles scale with it. A `textarea` keeps its own height (`--mds-input-textarea-min-height`).\n\n#### Other behavioral props\n\n- **`icon`** is an SVG filename slug from the Magma icon library shown at the leading (left) edge of the field; it is suppressed while `await` is active, since the spinner takes its place. A `color` field ignores it: its swatch stands there.\n- **`controlsLayout`** chooses between stacked (`'vertical'`) and split (`'horizontal'`) stepper buttons, and **`controlsIcon`** picks arrow vs. plus/minus glyphs - both apply only to `type=\"number\"`.\n- **`datalist`** supplies suggestion options for `type=\"search\"` style autocompletion.\n- **`tip`** renders inline helper text below the field, and **`typography`** selects the field's text scale.\n",
|
|
13934
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-input>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Text Input\n\nThe simplest form: set `name` for form participation and `placeholder` for a visual hint. Wrap the component in [`mds-input-field`](../mds-input-field/AGENTS.md) to add a visible label and associated tip.\n\n```html\n<mds-input\n name=\"cognome\"\n placeholder=\"Inserisci il tuo cognome\"\n></mds-input>\n```\n\n#### Required Field with `tip` Helper Text\n\nUse `required` to validate that the field is not empty and `tip` to explain the constraint. The component surfaces a top-tip when focused and drives `variant` to `'error'` or `'success'` on blur. When the field collects the user's own data, set the matching `autocomplete` token (`email`, `given-name`, `tel`, ...) so browsers can identify its purpose (WCAG 2.1 SC 1.3.5) and offer autofill; without it the component default `autocomplete=\"off\"` applies.\n\n```html\n<mds-input\n name=\"email\"\n type=\"email\"\n autocomplete=\"email\"\n placeholder=\"nome@esempio.it\"\n required\n tip=\"Inserisci un indirizzo email valido\"\n></mds-input>\n```\n\n#### Textarea for Multi-line Content\n\nSet `type=\"textarea\"` to render a `<textarea>` instead of a single-line `<input>`. Use the `--mds-input-textarea-*` custom properties to control height and resize behaviour.\n\n```html\n<mds-input\n name=\"descrizione\"\n type=\"textarea\"\n placeholder=\"Descrivi il problema...\"\n maxlength=\"500\"\n></mds-input>\n```\n\n#### Character Counter via `maxlength`\n\nWhen `maxlength` is set the component renders a live `current / max` counter below the field. The counter shifts through fullness variants as the limit approaches. A value of `0` or less is treated as unset.\n\n```html\n<mds-input\n name=\"titolo\"\n placeholder=\"Titolo dell'articolo\"\n maxlength=\"120\"\n></mds-input>\n```\n\n#### Numeric Input with Steppers\n\nSet `type=\"number\"` to enable built-in increment/decrement buttons. Use `controlsLayout` to choose between stacked (`'vertical'`, default) and split (`'horizontal'`) placement, and `controlsIcon` to pick arrow vs. plus/minus glyphs. Use `min`, `max`, and `step` to constrain the legal range. A `readonly` or `disabled` number shows no steppers: the value cannot change there.\n\n```html\n<!-- Stacked (default) - arrow glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"1\"\n max=\"99\"\n step=\"1\"\n placeholder=\"1\"\n></mds-input>\n\n<!-- Horizontal split - arithmetic glyphs -->\n<mds-input\n name=\"quantita\"\n type=\"number\"\n min=\"0\"\n max=\"100\"\n controls-layout=\"horizontal\"\n controls-icon=\"arithmetic\"\n placeholder=\"0\"\n></mds-input>\n```\n\n#### Password Input\n\nSet `type=\"password\"` to render a masked field with a built-in visibility toggle. The component renders a custom dot-mask overlay and a show/hide button - no extra wiring is needed. Always set `autocomplete` to `new-password` (sign-up, password change) or `current-password` (login): the component default is `autocomplete=\"off\"`, which browsers and password managers ignore on credential fields, but the explicit token is what lets them pair the password with its username field and fill or generate the right value.\n\n```html\n<mds-input\n name=\"password\"\n type=\"password\"\n autocomplete=\"new-password\"\n placeholder=\"Scegli una password\"\n required\n></mds-input>\n```\n\n#### Login Form\n\nPair a username field carrying `autocomplete=\"username\"` with a password field carrying `autocomplete=\"current-password\"` inside a `<form>`, and submit through `<mds-button type=\"submit\">`. The native fields live in the Shadow DOM of each `<mds-input>`: among the password managers tested, Bitwarden, LastPass, Chrome and Edge detect and fill them, Firefox's built-in manager and KeePassXC-Browser do not (they only look at the light DOM).\n\n```html\n<form action=\"/login\" method=\"post\">\n <mds-input-field label=\"Email\">\n <mds-input name=\"username\" type=\"email\" autocomplete=\"username\" required></mds-input>\n </mds-input-field>\n <mds-input-field label=\"Password\">\n <mds-input name=\"password\" type=\"password\" autocomplete=\"current-password\" required></mds-input>\n </mds-input-field>\n\n <mds-button type=\"submit\" label=\"Accedi\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Italian-Specific Masked Types\n\n`type=\"cf\"` installs the codice fiscale format and length validators and `type=\"isbn\"` a checksum validator. `type=\"piva\"` accepts 11 digits whose last one is the check digit, without the `IT` prefix or spaces, and `type=\"cc\"` 13 to 19 digits, in groups split by spaces or dashes, that pass the Luhn check of card numbers. A value that breaks the format stops the submit of the form. No type applies a keyboard mask.\n\n```html\n<mds-input name=\"codice_fiscale\" type=\"cf\" placeholder=\"RSSMRA80A01H501Z\"></mds-input>\n<mds-input name=\"partita_iva\" type=\"piva\" placeholder=\"01234567890\"></mds-input>\n```\n\n#### Colour Field\n\nSet `type=\"color\"` to ask for a colour: the code is typed in the field, or picked with the button at its end (or a click on the swatch at its start), which opens the picker of the platform. The value is `#rrggbb` in lower case, in `mdsInputChange` and in the form; the field also takes `#rgb` and the code without `#`, in any case, and writes it as `#rrggbb` when it is left. Wrap it in `mds-input-field`: the label names the field and its picker button, the message shows the error of a text that names no colour. A field that is not `required` can stay empty.\n\n```html\n<mds-input-field label=\"Colore di base\">\n <mds-input name=\"base\" type=\"color\" value=\"#2f6fd0\" placeholder=\"#rrggbb\" required></mds-input>\n</mds-input-field>\n```\n\n```javascript\ndocument.querySelector('mds-input[type=\"color\"]').addEventListener('mdsInputChange', (e) => {\n // a colour as #rrggbb, or '' while the field is empty or its text names no colour\n if (e.detail.value) applyColour(e.detail.value);\n});\n```\n\n#### Search Input with Datalist\n\nUse `type=\"search\"` combined with the `datalist` prop to offer autocomplete suggestions from a fixed list. The list is rendered inside the shadow DOM and wired automatically.\n\n```html\n<mds-input\n name=\"comune\"\n type=\"search\"\n placeholder=\"Cerca comune...\"\n></mds-input>\n```\n\n```javascript\n// Pass suggestions as a JavaScript array\ndocument.querySelector('mds-input').datalist = ['Roma', 'Milano', 'Napoli', 'Torino'];\n```\n\n#### Icon Decoration\n\nThe `icon` prop renders an SVG slug from the Magma icon library at the leading edge of the field. The icon is suppressed while `await` is active and the spinner takes its place.\n\n```html\n<mds-input\n name=\"cerca\"\n type=\"search\"\n icon=\"mi/baseline/search\"\n placeholder=\"Cerca...\"\n></mds-input>\n```\n\n#### AI-Assisted Field\n\nSet `variant=\"ai\"` to signal an AI-powered field. When no `icon` prop is present, the component auto-assigns the AI chatbot icon.\n\n```html\n<mds-input\n name=\"prompt\"\n type=\"text\"\n variant=\"ai\"\n placeholder=\"Chiedi qualcosa all'assistente...\"\n></mds-input>\n```\n\n#### Async Loading via `await`\n\nSet the `await` boolean attribute while an async operation (e.g. a lookup) is in flight. The component renders an inline spinner in place of the icon. Remove the attribute when done - do not set `await=\"false\"`.\n\n```html\n<mds-input name=\"codice\" placeholder=\"Verifica in corso...\" await></mds-input>\n```\n\n#### Speech-to-Text Dictation\n\nSet the `mic` boolean attribute to render a dictation button. Starting a dictation clears the current value and writes the recognized speech in its place; the component emits `mdsInputSpeechEnd` when the user stops the dictation. If the Web Speech API is unavailable the button switches to an error state and the value is kept. A read-only or disabled field has no dictation button.\n\n```html\n<mds-input\n name=\"note_vocali\"\n type=\"text\"\n mic\n placeholder=\"Parla o scrivi...\"\n></mds-input>\n```\n\n#### Listening to Events\n\nListen for `mdsInputChange` instead of native `input` or `change`: `change` does not cross the shadow boundary, and `input` reports only typing, not the values set by the steppers, the dictation or a script.\n\n```javascript\ndocument.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {\n console.log(e.detail.value);\n});\n\ndocument.querySelector('mds-input').addEventListener('mdsInputValidation', (e) => {\n console.log('valido:', e.detail);\n});\n```\n\n#### Form Participation\n\n`<mds-input>` is form-associated. It submits natively inside a `<form>`; set `name` so the value is included in form data. Its validation is reported to the form too: an empty `required` field, or one that breaks another rule, stops the submit like a native input and shows the error. Add `novalidate` to the `<form>` when your own code validates on submit. A reset brings every field back to its value at load and to its pristine look.\n\n```html\n<form action=\"/salva\" method=\"post\">\n <mds-input name=\"nome\" type=\"text\" placeholder=\"Nome\" required></mds-input>\n <mds-input name=\"cognome\" type=\"text\" placeholder=\"Cognome\" required></mds-input>\n <mds-input name=\"email\" type=\"email\" placeholder=\"Email\" required></mds-input>\n\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Annulla\" variant=\"dark\" tone=\"outline\"></mds-button>\n</form>\n```\n\n#### Read-Only Display\n\nUse `readonly` when the value should be visible but not editable. A persistent top tip, on the top border of the field, describes the state, and the field text is auto-selected on focus for easy copying. The buttons that change the value (steppers, dictation, colour picker) are not shown; the password toggle stays.\n\n```html\n<mds-input\n name=\"codice_riferimento\"\n value=\"REF-2024-00123\"\n readonly\n></mds-input>\n```\n\n#### Styling Customization\n\nStyle the input only through its public `--mds-input-*` CSS custom properties. Set them on the host or a parent selector. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.search-bar mds-input {\n --mds-input-background: rgb(var(--magma-wash-base));\n}\n\n/* Textarea: fixed height, allow resize */\n.notes-area mds-input {\n --mds-input-textarea-min-height: 8rem;\n --mds-input-textarea-max-height: 24rem;\n --mds-input-textarea-resize: vertical;\n}\n```\n\n#### Sizing a Field to the Controls Next to It\n\nGive the fields of a row the `size` of the buttons beside them, so they share one height: `sm` 28px, `md` 36px, `lg` 48px (default), the sizes of [`<mds-button>`](../mds-button/AGENTS.md). `<mds-input-select>`, `<mds-input-date>` and `<mds-input-date-range>` take the same values.\n\n```html\n<div class=\"flex items-center gap-200\">\n <mds-input size=\"md\" type=\"search\" icon=\"mi/baseline/search\" placeholder=\"Cerca\"></mds-input>\n <mds-input-select size=\"md\" placeholder=\"Stato\">\n <option value=\"open\">Aperte</option>\n <option value=\"closed\">Chiuse</option>\n </mds-input-select>\n <mds-button size=\"md\" label=\"Filtra\"></mds-button>\n</div>\n```\n\n",
|
|
13935
|
+
"3. Mistakes": "Common incorrect uses of `<mds-input>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Raw `<input>` When `<mds-input>` Exists\n\nReaching for a plain `<input>` bypasses theming, validation, tips, accessible state announcements, and form-reset behavior provided by the component.\n\n```html\n<!-- INCORRECT -->\n<input type=\"text\" name=\"nome\" placeholder=\"Nome\" class=\"my-input\">\n\n<!-- CORRECT -->\n<mds-input name=\"nome\" type=\"text\" placeholder=\"Nome\"></mds-input>\n```\n\n#### Do Not Use a Native `<input type=\"color\">` in a Form of Magma\n\nThe native colour input looks like no other field of the form, has no text to type or paste a code into, no message, no variant and no label of `mds-input-field`, and always holds a colour (`#000000`), so it cannot be left empty. `type=\"color\"` gives the field of Magma with the picker of the platform on the button at its end.\n\n```html\n<!-- INCORRECT -->\n<label>Colore di base <input type=\"color\" name=\"base\" value=\"#2f6fd0\"></label>\n\n<!-- CORRECT -->\n<mds-input-field label=\"Colore di base\">\n <mds-input type=\"color\" name=\"base\" value=\"#2f6fd0\"></mds-input>\n</mds-input-field>\n```\n\n#### Do Not Set Boolean Attributes to the String `\"false\"`\n\n`disabled`, `required`, `readonly`, `mic` and `await` are boolean attributes: remove the attribute entirely to turn it off. `mds-input` is form-associated, so as on a native control any value turns them on, `\"false\"` included: this markup renders a disabled, required field.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"note\" disabled=\"false\" required=\"false\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input name=\"note\"></mds-input>\n```\n\n#### Do Not Force `variant` for Validation Feedback\n\nThe component drives `variant` to `'success'` or `'error'` automatically on blur when validators are active. Setting `variant` manually overrides the feedback and breaks the visual contract.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"codice\" variant=\"error\" tip=\"Valore non valido\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input name=\"codice\" required tip=\"Inserisci un valore valido\"></mds-input>\n```\n\n#### Do Not Listen to Native `input` or `change` Events\n\nThe native `change` event does not cross the shadow boundary, and `input` reports only typing, not the values set by the steppers, the dictation or a script. Use the documented `mdsInputChange` event instead, which fires for every value change.\n\n```javascript\n// INCORRECT\ndocument.querySelector('mds-input').addEventListener('input', (e) => {\n console.log(e.target.value);\n});\n\n// CORRECT\ndocument.querySelector('mds-input').addEventListener('mdsInputChange', (e) => {\n console.log(e.detail.value);\n});\n```\n\n#### Do Not Use `type=\"number\"` Native Browser Spinners and Then Override the Input\n\nThe component renders its own increment/decrement buttons and hides the native browser spinners. Do not try to re-enable them via CSS, and do not add inline JS `stepUp`/`stepDown` calls - use the `controlsLayout` and `controlsIcon` props to configure the built-in controls.\n\n```html\n<!-- INCORRECT -->\n<mds-input type=\"number\" style=\"-moz-appearance: auto;\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input\n type=\"number\"\n controls-layout=\"horizontal\"\n controls-icon=\"arithmetic\"\n min=\"0\"\n max=\"100\"\n></mds-input>\n```\n\n#### Do Not Use a Legacy or Invalid `type` Value\n\n`<mds-input>` accepts a specific set of `type` values: `text`, `email`, `number`, `password`, `search`, `tel`, `url`, `date`, `time`, `textarea`, `cf`, `piva`, `cc`, `isbn`. Supplying anything else (e.g. `\"checkbox\"`, `\"radio\"`, `\"file\"`) is passed straight to the inner native `<input>`, which renders a bare native control that the component neither styles nor reports correctly to the form. Use the dedicated Magma component for those controls.\n\n```html\n<!-- INCORRECT -->\n<mds-input type=\"checkbox\" name=\"accetto\"></mds-input>\n<mds-input type=\"file\" name=\"allegato\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input-switch name=\"accetto\"></mds-input-switch>\n<mds-input-upload name=\"allegato\"></mds-input-upload>\n```\n\n#### Do Not Use `placeholder` as the Accessible Label\n\n`placeholder` disappears on input and is never read as a label by assistive tech. Always pair `<mds-input>` with [`mds-input-field`](../mds-input-field/AGENTS.md) (which shows a visible label and passes it down as the accessible name) or supply `aria-label` directly on the host.\n\n```html\n<!-- INCORRECT -->\n<mds-input name=\"ricerca\" placeholder=\"Cerca per nome\"></mds-input>\n\n<!-- CORRECT -->\n<mds-input-field label=\"Cerca per nome\">\n <mds-input name=\"ricerca\" placeholder=\"Cerca per nome\"></mds-input>\n</mds-input-field>\n```\n\n#### Do Not Pierce the Shadow DOM to Style Internal Parts\n\nThe supported customization surface is the public `--mds-input-*` CSS custom properties plus the documented shadow parts (`field`, `tip-top`, `tip-bottom`, `tip-count`, `password-toggle-button`, `counter-button-increase`, `counter-button-decrease`, `mic-toggle-button`, `color-picker-button`). Targeting undocumented internals via `>>>` or arbitrary class names couples your code to the Shadow DOM implementation.\n\n```css\n/* INCORRECT */\nmds-input >>> .input {\n border: 2px solid red;\n}\n\n/* CORRECT */\nmds-input {\n --mds-input-ring: 0 0 0 2px rgb(var(--magma-danger-border));\n --mds-input-background: rgb(var(--magma-danger-wash-base));\n}\nmds-input::part(field) {\n font-style: italic;\n}\n```\n"
|
|
13699
13936
|
},
|
|
13700
13937
|
"props": [
|
|
13701
13938
|
{
|
|
@@ -14020,7 +14257,7 @@
|
|
|
14020
14257
|
"mutable": false,
|
|
14021
14258
|
"attr": "await",
|
|
14022
14259
|
"reflectToAttr": true,
|
|
14023
|
-
"docs": "Specifies if the spinner icon is shown, replacing the icon if present",
|
|
14260
|
+
"docs": "Specifies if the spinner icon is shown, replacing the icon if present. A `color` field keeps\nits swatch, which shows the value, and shows the spinner at its end, before the picker button\n(read-only or disabled, the field has no picker button and the spinner takes the end)",
|
|
14024
14261
|
"docsTags": [
|
|
14025
14262
|
{
|
|
14026
14263
|
"name": "default",
|
|
@@ -14056,7 +14293,7 @@
|
|
|
14056
14293
|
"mutable": false,
|
|
14057
14294
|
"attr": "controls-icon",
|
|
14058
14295
|
"reflectToAttr": true,
|
|
14059
|
-
"docs": "Specifies the icon type of the counter
|
|
14296
|
+
"docs": "Specifies the icon type of the counter buttons when the input type is set to `number`",
|
|
14060
14297
|
"docsTags": [
|
|
14061
14298
|
{
|
|
14062
14299
|
"name": "default",
|
|
@@ -14100,7 +14337,7 @@
|
|
|
14100
14337
|
"mutable": false,
|
|
14101
14338
|
"attr": "controls-layout",
|
|
14102
14339
|
"reflectToAttr": true,
|
|
14103
|
-
"docs": "Specifies the layout of the counter
|
|
14340
|
+
"docs": "Specifies the layout of the counter buttons when the input type is set to `number`: stacked at\nthe end (`vertical`) or one at each end (`horizontal`). A read-only or disabled field has no\ncounter buttons, and its text takes the room they leave",
|
|
14104
14341
|
"docsTags": [
|
|
14105
14342
|
{
|
|
14106
14343
|
"name": "default",
|
|
@@ -14162,7 +14399,7 @@
|
|
|
14162
14399
|
"mutable": false,
|
|
14163
14400
|
"attr": "disabled",
|
|
14164
14401
|
"reflectToAttr": true,
|
|
14165
|
-
"docs": "If true, the element is displayed as disabled",
|
|
14402
|
+
"docs": "If true, the element is displayed as disabled. The buttons that change the value (the counter\nbuttons of a number, the microphone, the picker of a colour) are not shown: the end of the\nfield is left to the badge of its state",
|
|
14166
14403
|
"docsTags": [
|
|
14167
14404
|
{
|
|
14168
14405
|
"name": "default",
|
|
@@ -14194,7 +14431,7 @@
|
|
|
14194
14431
|
"mutable": true,
|
|
14195
14432
|
"attr": "icon",
|
|
14196
14433
|
"reflectToAttr": true,
|
|
14197
|
-
"docs": "An icon displayed at the left of the input, inside the field; the spinner of `await` takes\nits place",
|
|
14434
|
+
"docs": "An icon displayed at the left of the input, inside the field; the spinner of `await` takes\nits place. A `color` field ignores it: its swatch stands there, one mark at the start",
|
|
14198
14435
|
"docsTags": [],
|
|
14199
14436
|
"values": [
|
|
14200
14437
|
{
|
|
@@ -14280,7 +14517,7 @@
|
|
|
14280
14517
|
"mutable": false,
|
|
14281
14518
|
"attr": "mic",
|
|
14282
14519
|
"reflectToAttr": true,
|
|
14283
|
-
"docs": "Toggles text recognition",
|
|
14520
|
+
"docs": "Toggles text recognition. A read-only or disabled field has no dictation button. A `color`\nfield ignores it: a colour code is typed or picked, not dictated, and its end holds the button\nof the picker",
|
|
14284
14521
|
"docsTags": [],
|
|
14285
14522
|
"values": [
|
|
14286
14523
|
{
|
|
@@ -14449,7 +14686,7 @@
|
|
|
14449
14686
|
"mutable": false,
|
|
14450
14687
|
"attr": "readonly",
|
|
14451
14688
|
"reflectToAttr": true,
|
|
14452
|
-
"docs": "Specifies that the element is read-only",
|
|
14689
|
+
"docs": "Specifies that the element is read-only. The buttons that change the value (the counter\nbuttons of a number, the microphone, the picker of a colour) are not shown, as on a disabled\nfield; the password toggle stays, since it shows the value without changing it",
|
|
14453
14690
|
"docsTags": [
|
|
14454
14691
|
{
|
|
14455
14692
|
"name": "default",
|
|
@@ -14609,10 +14846,10 @@
|
|
|
14609
14846
|
},
|
|
14610
14847
|
{
|
|
14611
14848
|
"name": "type",
|
|
14612
|
-
"type": "\"cc\" | \"cf\" | \"date\" | \"email\" | \"isbn\" | \"number\" | \"password\" | \"piva\" | \"search\" | \"tel\" | \"text\" | \"textarea\" | \"time\" | \"url\" | undefined",
|
|
14849
|
+
"type": "\"cc\" | \"cf\" | \"color\" | \"date\" | \"email\" | \"isbn\" | \"number\" | \"password\" | \"piva\" | \"search\" | \"tel\" | \"text\" | \"textarea\" | \"time\" | \"url\" | undefined",
|
|
14613
14850
|
"complexType": {
|
|
14614
14851
|
"original": "InputTextType",
|
|
14615
|
-
"resolved": "\"cc\" | \"cf\" | \"date\" | \"email\" | \"isbn\" | \"number\" | \"password\" | \"piva\" | \"search\" | \"tel\" | \"text\" | \"textarea\" | \"time\" | \"url\" | undefined",
|
|
14852
|
+
"resolved": "\"cc\" | \"cf\" | \"color\" | \"date\" | \"email\" | \"isbn\" | \"number\" | \"password\" | \"piva\" | \"search\" | \"tel\" | \"text\" | \"textarea\" | \"time\" | \"url\" | undefined",
|
|
14616
14853
|
"references": {
|
|
14617
14854
|
"InputTextType": {
|
|
14618
14855
|
"location": "import",
|
|
@@ -14625,7 +14862,7 @@
|
|
|
14625
14862
|
"mutable": false,
|
|
14626
14863
|
"attr": "type",
|
|
14627
14864
|
"reflectToAttr": true,
|
|
14628
|
-
"docs": "Specifies the type of input element",
|
|
14865
|
+
"docs": "Specifies the type of input element. `color` holds a colour: the field stays a text field,\nwhere the code is typed and validated, with a swatch of the colour at its start and a button\nat its end that opens the colour picker of the platform. Its value, in the change event and\nin the form, is the colour as\n`#rrggbb` in lower case, or `''` while the text is empty or names no colour, which is a\nvalidation error; the text also takes `#rgb` and the code without `#`, in any case, and is\nwritten back as `#rrggbb` when the field is left",
|
|
14629
14866
|
"docsTags": [
|
|
14630
14867
|
{
|
|
14631
14868
|
"name": "default",
|
|
@@ -14642,6 +14879,10 @@
|
|
|
14642
14879
|
"value": "cf",
|
|
14643
14880
|
"type": "string"
|
|
14644
14881
|
},
|
|
14882
|
+
{
|
|
14883
|
+
"value": "color",
|
|
14884
|
+
"type": "string"
|
|
14885
|
+
},
|
|
14645
14886
|
{
|
|
14646
14887
|
"value": "date",
|
|
14647
14888
|
"type": "string"
|
|
@@ -14751,7 +14992,7 @@
|
|
|
14751
14992
|
"mutable": true,
|
|
14752
14993
|
"attr": "value",
|
|
14753
14994
|
"reflectToAttr": true,
|
|
14754
|
-
"docs": "Specifies the value of the input element",
|
|
14995
|
+
"docs": "Specifies the value of the input element. With `type=\"color\"`, a colour as `#rrggbb`: a value\nset as `#rgb`, without `#` or in upper case is written so, and one that names no colour is\nshown as it is, with its error, while the value becomes `''`",
|
|
14755
14996
|
"docsTags": [
|
|
14756
14997
|
{
|
|
14757
14998
|
"name": "default",
|
|
@@ -15237,19 +15478,19 @@
|
|
|
15237
15478
|
{
|
|
15238
15479
|
"name": "--mds-input-tip-horizontal-offset",
|
|
15239
15480
|
"annotation": "prop",
|
|
15240
|
-
"docs": "The default horizontal offset applied to the
|
|
15481
|
+
"docs": "The default horizontal offset applied to the bottom tip",
|
|
15241
15482
|
"visibility": "internal"
|
|
15242
15483
|
},
|
|
15243
15484
|
{
|
|
15244
15485
|
"name": "--mds-input-tip-horizontal-offset-focused",
|
|
15245
15486
|
"annotation": "prop",
|
|
15246
|
-
"docs": "The horizontal offset applied when the input
|
|
15487
|
+
"docs": "The horizontal offset applied to the bottom tip when the input is focused",
|
|
15247
15488
|
"visibility": "internal"
|
|
15248
15489
|
},
|
|
15249
15490
|
{
|
|
15250
15491
|
"name": "--mds-input-tip-vertical-offset",
|
|
15251
15492
|
"annotation": "prop",
|
|
15252
|
-
"docs": "The vertical offset applied to the
|
|
15493
|
+
"docs": "The vertical offset applied to the bottom tip",
|
|
15253
15494
|
"visibility": "internal"
|
|
15254
15495
|
},
|
|
15255
15496
|
{
|
|
@@ -15261,6 +15502,10 @@
|
|
|
15261
15502
|
],
|
|
15262
15503
|
"slots": [],
|
|
15263
15504
|
"parts": [
|
|
15505
|
+
{
|
|
15506
|
+
"name": "color-picker-button",
|
|
15507
|
+
"docs": "Selects the button that opens the colour picker of a `color` field"
|
|
15508
|
+
},
|
|
15264
15509
|
{
|
|
15265
15510
|
"name": "counter-button-decrease",
|
|
15266
15511
|
"docs": "Selects the button used to decrease the input value"
|
|
@@ -15352,8 +15597,8 @@
|
|
|
15352
15597
|
}
|
|
15353
15598
|
],
|
|
15354
15599
|
"usage": {
|
|
15355
|
-
"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
|
|
15356
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-input-date>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant ladder documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Date Input\n\nThe simplest form. Wrap in [`mds-input-field`](../mds-input-field/AGENTS.md) to attach a visible label. Use `name` so the value is submitted with the form.\n\n```html\n<mds-input-field label=\"Data di nascita\">\n <mds-input-date name=\"birthdate\"></mds-input-date>\n</mds-input-field>\n```\n\n#### Pre-filled Value\n\nSet `value` to an ISO date string (`YYYY-MM-DD`) to initialize the picker with a known date. Do not use other date formats.\n\n```html\n<mds-input-date name=\"dataScadenza\" value=\"2026-12-31\"></mds-input-date>\n```\n\n#### Required Field\n\nAdd `required` to make an empty or invalid date fail validation. The component surfaces a tip on focus; the field stops the submit while empty, and turns to `'error'` once the user leaves it empty or a stopped submit points at it, until a valid date is entered.\n\n```html\n<mds-input-field label=\"Data di inizio *\">\n <mds-input-date name=\"startDate\" required></mds-input-date>\n</mds-input-field>\n```\n\n#### Bounded Date Range\n\nUse `min` and `max` (both ISO strings) to restrict the selectable range. Dates outside the range invalidate the field and, once it is touched, emit `mdsInputValidation` with `false`. If `max` is earlier than `min` at load time, the component snaps `max` to equal `min`.\n\n```html\n<mds-input-date\n name=\"dataSopralluogo\"\n min=\"2026-01-01\"\n max=\"2026-12-31\"\n></mds-input-date>\n```\n\n#### Listening to Value Changes\n\nListen to `mdsInputDateSelect` (fires with the new ISO string) for every value change - whether typed or picked from the calendar. Listen to `mdsInputValidation` to react to validity changes.\n\n```html\n<mds-input-date id=\"picker\" name=\"dataEvento\"></mds-input-date>\n\n<script>\n const picker = document.getElementById('picker');\n\n picker.addEventListener('mdsInputDateSelect', (e) => {\n console.log('Data selezionata:', e.detail); // \"2026-06-15\"\n });\n\n picker.addEventListener('mdsInputValidation', (e) => {\n console.log('Valido:', e.detail); // true | false\n });\n</script>\n```\n\n#### Programmatic Value via `setValue`\n\nUse the `setValue` method to set the value from JavaScript; it emits `mdsInputDateSelect` and checks the value. Unlike a user interaction it does not touch the field: on a pristine field the validity reaches the form, but the variant and `mdsInputValidation` wait for the user.\n\n```html\n<mds-input-date id=\"datePicker\" name=\"dataConsegna\"></mds-input-date>\n\n<script>\n document.getElementById('datePicker').setValue('2026-09-01');\n</script>\n```\n\n#### Controlling Calendar Auto-close Delay\n\nThe calendar dropdown closes `delay` milliseconds after a date is picked (default 500 ms). Set `delay=\"0\"` to keep it open after selection - useful when the picker is used inside a form where the user might want to confirm before the overlay disappears.\n\n```html\n<!-- Default: closes 500 ms after pick -->\n<mds-input-date name=\"dataRiunione\" delay=\"500\"></mds-input-date>\n\n<!-- Keep open until the user dismisses manually -->\n<mds-input-date name=\"dataRiunione\" delay=\"0\"></mds-input-date>\n```\n\n#### Disabled and Read-only States\n\n`disabled` blocks all interaction and removes the field from the tab sequence. `readonly` keeps the field in the tab sequence and selects its text on focus, but the date cannot be changed: the native input is read-only and
|
|
15600
|
+
"1. Description": "The `<mds-input-date>` web component is the Magma Design System control for capturing a single calendar date. It wraps a native `<input type=\"date\">`, adding form association, ISO value validation against an optional `min`/`max` range, contextual tips, and a button-triggered calendar dropdown for visual date picking.\n\n#### Semantic Behavior\n\n- **Form association**: The host participates natively in form submission and exposes its `value` under `name`; a form reset brings back the date the field had at load, both shown and submitted, and its pristine look, like a native input. An invalid value submits nothing, and its invalid state is reported to the form: like a native control, the field matches `:invalid` and stops the submit, with a message in the page language (a missing required date, a date out of the range, an unreadable one). A disabled or read-only field is left out, and `novalidate` on the `<form>` turns the check off.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **ISO value contract**: `value`, `min`, and `max` are all ISO date strings (`YYYY-MM-DD`); other formats are not accepted.\n- **Validation on change**: The value is checked when the component loads, on every value change and whenever `required`, `min` or `max` change (also after load, as with the React wrappers under SSR). The validity reported to the form, the submitted value and the required tip follow every check: a date invalid, missing while `required` or outside the `min`/`max` range submits no value. The look follows once the field is touched, like `:user-invalid` on a native control: after the user edits or leaves the field, picks a date from the calendar, or a stopped submit points at it, each check sets `variant` to `'error'` or `'primary'` and emits `mdsInputValidation` with a boolean. An empty `required` field therefore loads in its own variant, not in `'error'`.\n- **Range self-correction**: If `max` is earlier than `min`, at load or after a later change of either, `max` is snapped to equal `min`.\n- **Selection event**: `mdsInputDateSelect` fires with the new string value whenever `value` changes, whether typed or picked from the calendar.\n- **Calendar dropdown**: The trailing calendar button, icon-only and named in the page language (the `lang` of `<html>`) (\"Open calendar\"), opens a single-date calendar; picking a day writes back the value and, after `delay`, auto-closes. It is shown only while the user can change the date: a read-only or disabled field (a disabled `<fieldset>` included) has no calendar button, its text takes its room and its end is left to the badge of its state; a calendar open on a field that becomes so closes.\n- **Slotted mode**: When the host carries a `slot` attribute it is treated as embedded - the calendar button, dropdown, and calendar are not rendered, leaving only the bare input for composition inside a larger field.\n- **Contextual tips**: A tip surfaces `disabled`, `readonly`, and `required` states; the required tip expands on focus and reflects success once the value is valid. It stands on the top border of the field, half outside, clear of its rounded corner, and stays there while the field has the focus, as on `mds-input`.\n- **Read-only**: A read-only field shows its tip and auto-selects its text on focus; its native input is read-only and it has no calendar button, so the value cannot be changed.\n\n#### Properties & Visual Configurations\n\nThe shared `variant` ladder is defined in [`agents/variants.md`](../../../../agents/variants.md). Note that `variant` is mutable here: once the field is touched, the component overrides it to `'error'` / `'primary'` as validation dictates, so a variant set in the markup or from script lasts until the user edits or leaves the field.\n\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner calendar button scale with it.\n\n#### Other behavioral props\n\n- **`min`** / **`max`** bound the selectable range; dates outside it invalidate the field rather than being silently clamped.\n- **`delay`** is the milliseconds to wait before auto-closing the calendar dropdown after a pick; setting it to `0` keeps the dropdown open.\n- **`required`** makes an empty or invalid value fail validation and drives the required/required-success tip.\n",
|
|
15601
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-input-date>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant ladder documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Date Input\n\nThe simplest form. Wrap in [`mds-input-field`](../mds-input-field/AGENTS.md) to attach a visible label. Use `name` so the value is submitted with the form.\n\n```html\n<mds-input-field label=\"Data di nascita\">\n <mds-input-date name=\"birthdate\"></mds-input-date>\n</mds-input-field>\n```\n\n#### Pre-filled Value\n\nSet `value` to an ISO date string (`YYYY-MM-DD`) to initialize the picker with a known date. Do not use other date formats.\n\n```html\n<mds-input-date name=\"dataScadenza\" value=\"2026-12-31\"></mds-input-date>\n```\n\n#### Required Field\n\nAdd `required` to make an empty or invalid date fail validation. The component surfaces a tip on focus; the field stops the submit while empty, and turns to `'error'` once the user leaves it empty or a stopped submit points at it, until a valid date is entered.\n\n```html\n<mds-input-field label=\"Data di inizio *\">\n <mds-input-date name=\"startDate\" required></mds-input-date>\n</mds-input-field>\n```\n\n#### Bounded Date Range\n\nUse `min` and `max` (both ISO strings) to restrict the selectable range. Dates outside the range invalidate the field and, once it is touched, emit `mdsInputValidation` with `false`. If `max` is earlier than `min` at load time, the component snaps `max` to equal `min`.\n\n```html\n<mds-input-date\n name=\"dataSopralluogo\"\n min=\"2026-01-01\"\n max=\"2026-12-31\"\n></mds-input-date>\n```\n\n#### Listening to Value Changes\n\nListen to `mdsInputDateSelect` (fires with the new ISO string) for every value change - whether typed or picked from the calendar. Listen to `mdsInputValidation` to react to validity changes.\n\n```html\n<mds-input-date id=\"picker\" name=\"dataEvento\"></mds-input-date>\n\n<script>\n const picker = document.getElementById('picker');\n\n picker.addEventListener('mdsInputDateSelect', (e) => {\n console.log('Data selezionata:', e.detail); // \"2026-06-15\"\n });\n\n picker.addEventListener('mdsInputValidation', (e) => {\n console.log('Valido:', e.detail); // true | false\n });\n</script>\n```\n\n#### Programmatic Value via `setValue`\n\nUse the `setValue` method to set the value from JavaScript; it emits `mdsInputDateSelect` and checks the value. Unlike a user interaction it does not touch the field: on a pristine field the validity reaches the form, but the variant and `mdsInputValidation` wait for the user.\n\n```html\n<mds-input-date id=\"datePicker\" name=\"dataConsegna\"></mds-input-date>\n\n<script>\n document.getElementById('datePicker').setValue('2026-09-01');\n</script>\n```\n\n#### Controlling Calendar Auto-close Delay\n\nThe calendar dropdown closes `delay` milliseconds after a date is picked (default 500 ms). Set `delay=\"0\"` to keep it open after selection - useful when the picker is used inside a form where the user might want to confirm before the overlay disappears.\n\n```html\n<!-- Default: closes 500 ms after pick -->\n<mds-input-date name=\"dataRiunione\" delay=\"500\"></mds-input-date>\n\n<!-- Keep open until the user dismisses manually -->\n<mds-input-date name=\"dataRiunione\" delay=\"0\"></mds-input-date>\n```\n\n#### Disabled and Read-only States\n\n`disabled` blocks all interaction and removes the field from the tab sequence. `readonly` keeps the field in the tab sequence and selects its text on focus, but the date cannot be changed: the native input is read-only and there is no calendar button. Both surface a contextual tip on the top border, and leave the end of the field to it.\n\n```html\n<!-- Disabled: no interaction at all -->\n<mds-input-date name=\"dataArchiviazione\" disabled value=\"2025-01-01\"></mds-input-date>\n\n<!-- Read-only: focusable, not editable -->\n<mds-input-date name=\"dataCreazione\" readonly value=\"2024-06-01\"></mds-input-date>\n```\n\n#### Form Participation\n\n`<mds-input-date>` is form-associated and submits its ISO value under `name`. A missing `required` date, or one out of the `min`/`max` range, stops the submit like a native control. A form reset brings back the date of load, both shown and submitted.\n\n```html\n<form action=\"/prenota\" method=\"post\">\n <mds-input-field label=\"Data prenotazione\">\n <mds-input-date name=\"bookingDate\" required></mds-input-date>\n </mds-input-field>\n <mds-button type=\"submit\" label=\"Conferma\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Slotted Mode Inside a Compound Field\n\nWhen the host carries a `slot` attribute, the component renders only the bare native input - the calendar button, dropdown, and calendar are suppressed. This is the correct way to embed the date input inside [`mds-input-date-range`](../mds-input-date-range/AGENTS.md) or a custom compound field.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\" name=\"rangeStart\"></mds-input-date>\n <mds-input-date slot=\"end\" name=\"rangeEnd\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Variant Override for External State Signalling\n\n`variant` is driven automatically by validation (`'error'` on invalid, `'primary'` on valid) once the field is touched. To communicate an external state, write it in the markup or set it from script: it lasts until the user edits or leaves the field. Values follow the theme input ladder: `primary` (default), `error`, `success`, `warning`, `info`, `ai`.\n\n```html\n<mds-input-date id=\"dataConferma\" name=\"dataConferma\" value=\"2026-03-15\"></mds-input-date>\n\n<script>\n // Pre-mark as success when the date was already validated server-side\n const field = document.getElementById('dataConferma');\n field.componentOnReady().then(() => {\n field.variant = 'success';\n });\n</script>\n```\n\n#### Styling Customization\n\nStyle the component only through its public `--mds-input-date-*` CSS custom properties. Use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast work automatically.\n\n```css\n.booking-widget mds-input-date {\n --mds-input-date-background: rgb(var(--magma-wash-base));\n --mds-input-date-ring: 0 0 0 2px rgb(var(--magma-border-focus) / 0.5);\n}\n```\n",
|
|
15357
15602
|
"3. Mistakes": "Common incorrect uses of `<mds-input-date>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use Non-ISO Date Strings\n\n`value`, `min`, and `max` must be ISO 8601 date strings (`YYYY-MM-DD`). Any other format is passed to `DateTime.fromISO`, which marks the date invalid: a non-ISO `value` immediately trips validation, and a non-ISO `min` / `max` is silently ignored.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date value=\"31/12/2026\" max=\"31-12-2026\"></mds-input-date>\n\n<!-- CORRECT -->\n<mds-input-date value=\"2026-12-31\" max=\"2026-12-31\"></mds-input-date>\n```\n\n#### Do Not Hardcode `variant=\"error\"` to Signal Validation\n\nThe component manages `variant` automatically: it sets `'error'` when validation fails and restores `'primary'` when it passes. Hardcoding `variant=\"error\"` shows an error before the user has done anything, does not stop the submit, and is overwritten as soon as the user touches the field.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date name=\"dataScadenza\" variant=\"error\"></mds-input-date>\n\n<!-- CORRECT - let validation drive variant; listen to mdsInputValidation instead -->\n<mds-input-date name=\"dataScadenza\" required></mds-input-date>\n```\n\n#### Do Not Listen to the Native `change` or `input` Events\n\nThe component emits `mdsInputDateSelect` (value string) and `mdsInputValidation` (boolean). The native `change` event does not cross the shadow boundary, and `input` misses calendar-driven picks and values set from script.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date id=\"picker\" name=\"data\"></mds-input-date>\n<script>\n document.getElementById('picker').addEventListener('change', handler);\n</script>\n\n<!-- CORRECT -->\n<mds-input-date id=\"picker\" name=\"data\"></mds-input-date>\n<script>\n document.getElementById('picker').addEventListener('mdsInputDateSelect', handler);\n</script>\n```\n\n#### Do Not Use a Raw `<input type=\"date\">` as a Drop-in Replacement\n\nReplacing `<mds-input-date>` with a plain `<input type=\"date\">` loses form-association conventions, theming, the calendar overlay, the contextual tip, and all Magma accessibility defaults.\n\n```html\n<!-- INCORRECT -->\n<input type=\"date\" name=\"dataEvento\" />\n\n<!-- CORRECT -->\n<mds-input-date name=\"dataEvento\"></mds-input-date>\n```\n\n#### Do Not Set `disabled=\"false\"` or `readonly=\"false\"` to Remove the State\n\nBoolean attributes must be absent to be off. `mds-input-date` is form-associated, so as on a native control any value turns them on, `\"false\"` included: this markup renders a disabled, read-only field.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date name=\"data\" disabled=\"false\" readonly=\"false\"></mds-input-date>\n\n<!-- CORRECT - remove the attribute entirely -->\n<mds-input-date name=\"data\"></mds-input-date>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Inner Input\n\nThe documented customization surface is the public `--mds-input-date-*` CSS custom properties plus the `::part(input-date)` part. Targeting internals with `>>>`, `/deep/`, or undocumented selectors will break on any minor release.\n\n```css\n/* INCORRECT */\nmds-input-date >>> .input {\n border: 2px solid red;\n}\n\n/* CORRECT */\nmds-input-date {\n --mds-input-date-ring: 0 0 0 2px rgb(var(--magma-danger-border) / 0.8);\n}\nmds-input-date::part(input-date) {\n font-size: var(--text-size-info-caption);\n}\n```\n\n#### Do Not Set `value` to Clear the Field\n\nSetting `value=\"\"` is the correct way to clear; do not set `value` to a non-ISO string expecting the component to silently ignore it - it passes through validation and trips an error state.\n\n```html\n<!-- INCORRECT (non-ISO value to \"reset\") -->\n<mds-input-date name=\"data\" value=\"clear\"></mds-input-date>\n\n<!-- CORRECT -->\n<mds-input-date name=\"data\" value=\"\"></mds-input-date>\n```\n"
|
|
15358
15603
|
},
|
|
15359
15604
|
"props": [
|
|
@@ -15427,7 +15672,7 @@
|
|
|
15427
15672
|
"mutable": false,
|
|
15428
15673
|
"attr": "disabled",
|
|
15429
15674
|
"reflectToAttr": true,
|
|
15430
|
-
"docs": "If true, the element is displayed as disabled",
|
|
15675
|
+
"docs": "If true, the element is displayed as disabled. The calendar button is not shown: the end of\nthe field is left to the badge of its state",
|
|
15431
15676
|
"docsTags": [
|
|
15432
15677
|
{
|
|
15433
15678
|
"name": "default",
|
|
@@ -15594,7 +15839,7 @@
|
|
|
15594
15839
|
"mutable": false,
|
|
15595
15840
|
"attr": "readonly",
|
|
15596
15841
|
"reflectToAttr": true,
|
|
15597
|
-
"docs": "Specifies that the element is read-only",
|
|
15842
|
+
"docs": "Specifies that the element is read-only: the date cannot be typed, and the calendar button is\nnot shown, as on a disabled field",
|
|
15598
15843
|
"docsTags": [
|
|
15599
15844
|
{
|
|
15600
15845
|
"name": "default",
|
|
@@ -15984,24 +16229,6 @@
|
|
|
15984
16229
|
"annotation": "prop",
|
|
15985
16230
|
"docs": "The background of the input tip",
|
|
15986
16231
|
"visibility": "public"
|
|
15987
|
-
},
|
|
15988
|
-
{
|
|
15989
|
-
"name": "--mds-input-tip-horizontal-offset",
|
|
15990
|
-
"annotation": "prop",
|
|
15991
|
-
"docs": "The horizontal offset for the input tip",
|
|
15992
|
-
"visibility": "internal"
|
|
15993
|
-
},
|
|
15994
|
-
{
|
|
15995
|
-
"name": "--mds-input-tip-horizontal-offset-focused",
|
|
15996
|
-
"annotation": "prop",
|
|
15997
|
-
"docs": "The horizontal offset when the input tip is focused",
|
|
15998
|
-
"visibility": "internal"
|
|
15999
|
-
},
|
|
16000
|
-
{
|
|
16001
|
-
"name": "--mds-input-tip-vertical-offset",
|
|
16002
|
-
"annotation": "prop",
|
|
16003
|
-
"docs": "The vertical offset for the input tip",
|
|
16004
|
-
"visibility": "internal"
|
|
16005
16232
|
}
|
|
16006
16233
|
],
|
|
16007
16234
|
"slots": [],
|
|
@@ -16071,8 +16298,8 @@
|
|
|
16071
16298
|
}
|
|
16072
16299
|
],
|
|
16073
16300
|
"usage": {
|
|
16074
|
-
"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**:
|
|
16075
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-input-date-range>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Minimal Range Picker\n\nThe canonical form. Slot one [`mds-input-date`](../mds-input-date/AGENTS.md) as `start` and another as `end`; the host wires them together, drives the shared calendar, and handles range validation automatically.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Pre-filling the Range\n\nUse the `start-date` and `end-date` attributes to set an initial selection. Both expect ISO `YYYY-MM-DD` strings. Changing them later re-syncs the slotted inputs and the calendar automatically.\n\n```html\n<mds-input-date-range start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Constraining the Selectable Window\n\nUse `min` and `max` to block out-of-window dates in the calendar. Both are ISO `YYYY-MM-DD` strings. The host passes them to the slotted fields too: a date typed out of the window turns its field to error, stops the submit of the form and is not emitted as a range.\n\n```html\n<mds-input-date-range min=\"2026-01-01\" max=\"2026-12-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Listening to Range Events\n\n`mdsInputDateRangeValueChange` fires when a full, valid range is committed (calendar pick, preset, or focus-out with two valid dates) and either bound actually changed since the last emit. It delivers `{ startDate, endDate }` in `event.detail`.\n\n```html\n<mds-input-date-range id=\"periodo\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<script>\n document.querySelector('#periodo').addEventListener('mdsInputDateRangeValueChange', (e) => {\n console.log('Intervallo selezionato:', e.detail.startDate, '-', e.detail.endDate);\n });\n</script>\n```\n\n#### Form Participation\n\n`<mds-input-date-range>` is form-associated. Add `name` and place it inside a `<form>`; the submitted value is a JSON string `{ startDate, endDate }`. An empty range submits no value. Form reset restores the dates set at first load.\n\n```html\n<form action=\"/filtra\" method=\"get\">\n <mds-input-date-range name=\"periodo\" start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n </mds-input-date-range>\n <mds-button type=\"submit\" label=\"Applica filtro\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Reimposta\" variant=\"dark\" tone=\"outline\"></mds-button>\n</form>\n```\n\n#### Quick-Pick Preselections\n\nSlot one or more [`mds-input-date-range-preselection`](../mds-input-date-range-preselection/AGENTS.md) elements into the component. They appear inside the calendar dropdown and act as one-click range shortcuts. The host marks the matching preset as selected, from load on and whenever the range changes to match it. A preset whose end comes before its start applies its start as both ends.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n <mds-input-date-range-preselection start=\"2026-06-02\" end=\"2026-06-08\">\n Questa settimana\n </mds-input-date-range-preselection>\n <mds-input-date-range-preselection start=\"2026-06-01\" end=\"2026-06-30\">\n Questo mese\n </mds-input-date-range-preselection>\n</mds-input-date-range>\n```\n\n#### Controlling the Auto-Close Delay\n\nBy default the calendar closes 500 ms after
|
|
16301
|
+
"1. Description": "The `<mds-input-date-range>` web component is the Magma Design System control for capturing a start/end date pair, composing two slotted `<mds-input-date>` fields with a shared pop-up `mds-calendar` (in range mode) and optional quick-pick presets. It is a form-associated compound parent that orchestrates its children rather than rendering its own native inputs.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects exactly two `<mds-input-date>` children assigned to the `start` and `end` named slots; the host keeps both in sync as a single range - it is not meant to be used with a default (text) slot.\n- **Form association**: The submitted value is a JSON string `{ startDate, endDate }`; an empty range submits no value. On form reset it restores the start/end dates present at first load.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables its calendar button as `disabled` does, while the slotted fields, being inside the fieldset too, follow it themselves: the range cannot be changed and is left out of the form, until the fieldset is enabled.\n- **Range coercion**: When both dates are valid and the end falls before the start, the end is snapped to equal the start, also for a preselection that ends before it starts, so the committed range is never inverted.\n- **Min/max guard**: If `max` is earlier than `min` at load, `max` is clamped up to `min`; both bounds are forwarded to the calendar to block out-of-range selection, and to the slotted fields, which flag a date typed outside them and stop the submit; such a range is not emitted.\n- **Commit on blur**: Leaving the component validates the range, syncs the form value, and - when both dates are valid - emits selection.\n- **Active end**: the calendar picks one end of the range at a time, the active one. The field the user goes into names it, by focus or by a click: the \"from\" field the start, the \"to\" field the end. With no field named yet, it is the end the range lacks (the start of an empty range, the end of a range with its start alone), else the start. With no start the calendar always picks the start: a range is picked from its start.\n- **Header**: the top of the panel shows the two ends, \"Start\" and \"End\", each with its date or \"Pick a date\", as an [`mds-tab`](../mds-tab/AGENTS.md) of two voices; the voice of the active end is selected, and a click or Enter / Space on a voice makes its end the active one. The end has nothing to pick, and its voice is disabled, until the range has a start. The words follow the page language, as \"from\" and \"to\".\n- **Calendar selection**: a click in the calendar changes the active end only, also on a complete range, which is no longer started again from scratch; then the end is the active one, so a range is picked with two clicks, start then end, and a second click corrects the end. A click never swaps the ends: a day before the start, while the end is picked, becomes the new start and the end is still to pick; a day after the end, while the start is picked, becomes the new start and the end is emptied. A click that completes the range emits selection; when it picks the end it also closes the dropdown after `delay`, unless `delay` is `0`, while one that picks the start leaves it open for the end.\n- **Preselection sync**: Slotted `mds-input-date-range-preselection` children act as quick-picks; activating one applies its range, and any external/calendar change re-evaluates which preset (if any) is marked selected; a preset matching the dates of load is marked selected from the start.\n- **Emitted events**: `mdsInputDateRangeValueChange` fires when a full, valid range is committed (calendar pick, preset, or focus-out with two valid dates) and either bound actually changed since the last emit.\n- **Focus management**: Clicking the host or either field label focuses the corresponding date input, and makes its end the active one; a built-in calendar icon button, named in the page language (the `lang` of `<html>`) (\"Open calendar\"), toggles the calendar dropdown. A pick in the calendar leaves the focus where it is: the header says which end comes next.\n- **Localization**: The \"from\"/\"to\" field labels, the words of the header and the calendar honor the resolved language (el/en/es/it).\n\n#### Properties & Visual Configurations\n\n- **`startDate` / `endDate`** are the controlled range bounds in ISO `YYYY-MM-DD` form; changing them externally re-syncs the slotted inputs and the calendar.\n- **`min` / `max`** define the selectable window: the calendar blocks the dates outside it, and the host passes both bounds to the slotted fields, which check a typed date against them. A bound the range does not set leaves the one written on a field alone; one changed after load reaches both fields.\n- **`disabled`** disables the range, like a disabled native input: the calendar button is disabled, a calendar left open closes, and the dates are left out of the form. It disables the two slotted fields too: at load only when it is set, so a field disabled on its own stays disabled; a change after load reaches both fields.\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner calendar button scale with it.\n- **`delay`** is the auto-close grace period (ms) after the click that picks the end of the range; set it to `0` to keep the calendar open until the user dismisses it manually.\n- **`dualCalendar`** shows two consecutive months side by side instead of one, whatever the width of the page; the grids of the two months start at the same height, a month of five weeks next to one of six.\n",
|
|
16302
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-input-date-range>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Minimal Range Picker\n\nThe canonical form. Slot one [`mds-input-date`](../mds-input-date/AGENTS.md) as `start` and another as `end`; the host wires them together, drives the shared calendar, and handles range validation automatically.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Picking a Range in the Calendar\n\nThe calendar picks one end at a time: the one of the field the user went into, or the one selected in the header at the top of the panel. In an empty range the first click picks the start and the header passes to the end; the second click picks the end and, after `delay`, closes the panel. To change one end of a complete range, go into its field (or select its voice in the header) and click the new day: the other end stays. A day before the start, picked as the end, becomes the new start; a day after the end, picked as the start, becomes the new start and empties the end. Nothing needs configuring: the markup is the one of the minimal picker.\n\n```html\n<mds-input-date-range start-date=\"2026-03-10\" end-date=\"2026-03-19\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Pre-filling the Range\n\nUse the `start-date` and `end-date` attributes to set an initial selection. Both expect ISO `YYYY-MM-DD` strings. Changing them later re-syncs the slotted inputs and the calendar automatically.\n\n```html\n<mds-input-date-range start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Constraining the Selectable Window\n\nUse `min` and `max` to block out-of-window dates in the calendar. Both are ISO `YYYY-MM-DD` strings. The host passes them to the slotted fields too: a date typed out of the window turns its field to error, stops the submit of the form and is not emitted as a range.\n\n```html\n<mds-input-date-range min=\"2026-01-01\" max=\"2026-12-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Listening to Range Events\n\n`mdsInputDateRangeValueChange` fires when a full, valid range is committed (calendar pick, preset, or focus-out with two valid dates) and either bound actually changed since the last emit. It delivers `{ startDate, endDate }` in `event.detail`.\n\n```html\n<mds-input-date-range id=\"periodo\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<script>\n document.querySelector('#periodo').addEventListener('mdsInputDateRangeValueChange', (e) => {\n console.log('Intervallo selezionato:', e.detail.startDate, '-', e.detail.endDate);\n });\n</script>\n```\n\n#### Form Participation\n\n`<mds-input-date-range>` is form-associated. Add `name` and place it inside a `<form>`; the submitted value is a JSON string `{ startDate, endDate }`. An empty range submits no value. Form reset restores the dates set at first load.\n\n```html\n<form action=\"/filtra\" method=\"get\">\n <mds-input-date-range name=\"periodo\" start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n </mds-input-date-range>\n <mds-button type=\"submit\" label=\"Applica filtro\" variant=\"primary\" tone=\"strong\"></mds-button>\n <mds-button type=\"reset\" label=\"Reimposta\" variant=\"dark\" tone=\"outline\"></mds-button>\n</form>\n```\n\n#### Quick-Pick Preselections\n\nSlot one or more [`mds-input-date-range-preselection`](../mds-input-date-range-preselection/AGENTS.md) elements into the component. They appear inside the calendar dropdown and act as one-click range shortcuts. The host marks the matching preset as selected, from load on and whenever the range changes to match it. A preset whose end comes before its start applies its start as both ends.\n\n```html\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n <mds-input-date-range-preselection start=\"2026-06-02\" end=\"2026-06-08\">\n Questa settimana\n </mds-input-date-range-preselection>\n <mds-input-date-range-preselection start=\"2026-06-01\" end=\"2026-06-30\">\n Questo mese\n </mds-input-date-range-preselection>\n</mds-input-date-range>\n```\n\n#### Controlling the Auto-Close Delay\n\nBy default the calendar closes 500 ms after the click that picks the end of the range; a click that picks the start leaves it open for the end. Set `delay=\"0\"` to keep it open until the user dismisses it manually, or increase the value for a longer grace period.\n\n```html\n<!-- Keep the calendar open after selection -->\n<mds-input-date-range delay=\"0\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<!-- Longer grace period: 1 second -->\n<mds-input-date-range delay=\"1000\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Styling Customization\n\nStyle the component only through its public `--mds-input-date-range-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` ([`agents/color.md`](../../../../agents/color.md)) so dark mode and themes keep working.\n\n```css\n.filtro-avanzato mds-input-date-range {\n --mds-input-date-range-background: rgb(var(--magma-surface-sunken));\n --mds-input-date-range-fields-gap: 0 calc(var(--spacing) * 400);\n}\n```\n",
|
|
16076
16303
|
"3. Mistakes": "Common incorrect uses of `<mds-input-date-range>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Omit the Named Slots\n\nThe host renders two named slots (`start` and `end`) and wires them together internally. Without slotted `<mds-input-date>` children the component has no visible inputs and no data to commit.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range start-date=\"2026-01-01\" end-date=\"2026-01-31\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Slot Raw `<input>` Elements\n\nThe `start` and `end` slots expect [`mds-input-date`](../mds-input-date/AGENTS.md) children. The host calls `.setValue()` and `.focusInput()` on the assigned element; a native `<input>` does not expose those methods and will break internal orchestration.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range>\n <input type=\"date\" slot=\"start\" />\n <input type=\"date\" slot=\"end\" />\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Disable the Fields Instead of the Range\n\nDisabling the slotted fields leaves the calendar button of the range enabled, and the user can still change the dates from the calendar. Set `disabled` on the range: it disables its calendar button and the two fields, and leaves the dates out of the form.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range name=\"period\">\n <mds-input-date slot=\"start\" disabled></mds-input-date>\n <mds-input-date slot=\"end\" disabled></mds-input-date>\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range name=\"period\" disabled>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Use Non-ISO Date Strings\n\n`startDate`, `endDate`, `min`, and `max` all require `YYYY-MM-DD` ISO format. Passing a locale-formatted string (e.g. `\"01/06/2026\"`) is silently invalid for Luxon's `DateTime.fromISO()` and leaves the range empty or unguarded.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range start-date=\"01/06/2026\" end-date=\"30/06/2026\" min=\"01/01/2026\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range start-date=\"2026-06-01\" end-date=\"2026-06-30\" min=\"2026-01-01\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Listen to Native `change` or `input` Events\n\nThe component emits `mdsInputDateRangeValueChange` as a documented custom event. Native `change` / `input` events originate from inside the shadow DOM and do not bubble out reliably.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range id=\"range\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n<script>\n document.querySelector('#range').addEventListener('change', handler);\n</script>\n\n<!-- CORRECT -->\n<mds-input-date-range id=\"range\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n<script>\n document.querySelector('#range').addEventListener('mdsInputDateRangeValueChange', handler);\n</script>\n```\n\n#### Do Not Set `delay=\"false\"` to Disable Auto-Close\n\n`delay` is a numeric prop, not a boolean. The string `\"false\"` is parsed as `NaN`, which is not `0`: the dropdown then closes at once instead of staying open. Use `delay=\"0\"` to keep the calendar open after selection.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range delay=\"false\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n\n<!-- CORRECT -->\n<mds-input-date-range delay=\"0\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n```\n\n#### Do Not Slot Preselection Elements Without the Component's Calendar\n\n[`mds-input-date-range-preselection`](../mds-input-date-range-preselection/AGENTS.md) children must be direct children of `<mds-input-date-range>`. Outside the component a click finds no range to apply (the preset looks for its closest `mds-input-date-range`); inside a wrapper div the preset is not slotted into the calendar dropdown and never shows.\n\n```html\n<!-- INCORRECT -->\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n</mds-input-date-range>\n<mds-input-date-range-preselection start=\"2026-06-01\" end=\"2026-06-30\">\n Questo mese\n</mds-input-date-range-preselection>\n\n<!-- CORRECT -->\n<mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n <mds-input-date-range-preselection start=\"2026-06-01\" end=\"2026-06-30\">\n Questo mese\n </mds-input-date-range-preselection>\n</mds-input-date-range>\n```\n\n#### Do Not Omit `name` When Inside a Form\n\nWithout `name` the component is form-associated but submits no named field, so the date range is invisible to the server and to `FormData`.\n\n```html\n<!-- INCORRECT -->\n<form action=\"/filtra\" method=\"get\">\n <mds-input-date-range>\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n </mds-input-date-range>\n</form>\n\n<!-- CORRECT -->\n<form action=\"/filtra\" method=\"get\">\n <mds-input-date-range name=\"periodo\">\n <mds-input-date slot=\"start\"></mds-input-date>\n <mds-input-date slot=\"end\"></mds-input-date>\n </mds-input-date-range>\n</form>\n```\n"
|
|
16077
16304
|
},
|
|
16078
16305
|
"props": [
|
|
@@ -16113,7 +16340,7 @@
|
|
|
16113
16340
|
"mutable": false,
|
|
16114
16341
|
"attr": "delay",
|
|
16115
16342
|
"reflectToAttr": true,
|
|
16116
|
-
"docs": "Specifies the delay in milliseconds before closing the calendar dropdown, if the value is 0 the dropdown will not close",
|
|
16343
|
+
"docs": "Specifies the delay in milliseconds before closing the calendar dropdown after the click that\npicks the end of the range, if the value is 0 the dropdown will not close; a click that picks\nthe start leaves it open for the end",
|
|
16117
16344
|
"docsTags": [
|
|
16118
16345
|
{
|
|
16119
16346
|
"name": "description",
|
|
@@ -16589,6 +16816,8 @@
|
|
|
16589
16816
|
"states": [],
|
|
16590
16817
|
"dependents": [],
|
|
16591
16818
|
"dependencies": [
|
|
16819
|
+
"mds-tab",
|
|
16820
|
+
"mds-tab-item",
|
|
16592
16821
|
"mds-calendar",
|
|
16593
16822
|
"mds-text",
|
|
16594
16823
|
"mds-button",
|
|
@@ -16596,20 +16825,25 @@
|
|
|
16596
16825
|
],
|
|
16597
16826
|
"dependencyGraph": {
|
|
16598
16827
|
"mds-input-date-range": [
|
|
16828
|
+
"mds-tab",
|
|
16829
|
+
"mds-tab-item",
|
|
16599
16830
|
"mds-calendar",
|
|
16600
16831
|
"mds-text",
|
|
16601
16832
|
"mds-button",
|
|
16602
16833
|
"mds-dropdown"
|
|
16603
16834
|
],
|
|
16604
|
-
"mds-
|
|
16605
|
-
"mds-button"
|
|
16606
|
-
"mds-calendar-cell"
|
|
16835
|
+
"mds-tab-item": [
|
|
16836
|
+
"mds-button"
|
|
16607
16837
|
],
|
|
16608
16838
|
"mds-button": [
|
|
16609
16839
|
"mds-icon",
|
|
16610
16840
|
"mds-spinner",
|
|
16611
16841
|
"mds-text"
|
|
16612
16842
|
],
|
|
16843
|
+
"mds-calendar": [
|
|
16844
|
+
"mds-button",
|
|
16845
|
+
"mds-calendar-cell"
|
|
16846
|
+
],
|
|
16613
16847
|
"mds-calendar-cell": [
|
|
16614
16848
|
"mds-button"
|
|
16615
16849
|
]
|
|
@@ -17244,7 +17478,7 @@
|
|
|
17244
17478
|
},
|
|
17245
17479
|
{
|
|
17246
17480
|
"name": "slot",
|
|
17247
|
-
"text": "-
|
|
17481
|
+
"text": "- The label of the range, as text. Add an `mds-input-range-value` per value to hold\nseveral values, a thumb each, on one track"
|
|
17248
17482
|
},
|
|
17249
17483
|
{
|
|
17250
17484
|
"name": "category",
|
|
@@ -17252,9 +17486,9 @@
|
|
|
17252
17486
|
}
|
|
17253
17487
|
],
|
|
17254
17488
|
"usage": {
|
|
17255
|
-
"1. Description": "The `<mds-input-range>` web component is the Magma Design System slider control for picking a
|
|
17256
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-input-range>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Slider with a Label\n\nThe minimum viable form. Put the field's text label in the default slot - it is rendered in the header and used as the accessible name for the underlying input. The default range is 0-100 with a step of 1.\n\n```html\n<mds-input-range name=\"volume\">Volume</mds-input-range>\n```\n\n#### Setting `min`, `max`, and `step`\n\nConstrain the range to a meaningful interval. Use `step` to enforce granularity - the component snaps the selected value to the nearest multiple automatically.\n\n```html\n<!-- Percentage slider, 5-point increments -->\n<mds-input-range name=\"completamento\" min=\"0\" max=\"100\" step=\"5\">Completamento (%)</mds-input-range>\n\n<!-- Temperature slider, half-degree steps -->\n<mds-input-range name=\"temperatura\" min=\"16\" max=\"30\" step=\"0.5\">Temperatura (C)</mds-input-range>\n```\n\n#### Pre-selected Value via `value`\n\nPass `value` to initialize the thumb at a specific position. The prop is reflected, so it also stays in sync when the user drags.\n\n```html\n<mds-input-range name=\"priorita\" min=\"1\" max=\"10\" value=\"7\">Priorita</mds-input-range>\n```\n\n#### Listening to `mdsInputRangeChange`\n\nThe component emits `mdsInputRangeChange` with the new numeric value in `event.detail` whenever the committed value changes. Do not listen to the raw `input` or `change` events - they may not bubble out of shadow DOM as expected.\n\n```html\n<mds-input-range id=\"rating\" name=\"valutazione\" min=\"1\" max=\"5\">Valutazione</mds-input-range>\n\n<script>\n document.querySelector('#rating').addEventListener('mdsInputRangeChange', (event) => {\n console.log('Nuovo valore:', event.detail);\n });\n</script>\n```\n\n#### Custom Value Display with `formatValue`\n\nSupply a `(value: number) => string` function to `formatValue` to change how the current value is shown in the header label - for example to add a unit suffix, format as currency, or humanize byte counts. The underlying numeric `value` is not affected.\n\n```html\n<mds-input-range id=\"prezzo\" name=\"prezzo\" min=\"0\" max=\"10000\" step=\"50\">Prezzo massimo</mds-input-range>\n\n<script>\n document.querySelector('#prezzo').formatValue = (v) =>\n v.toLocaleString('it-IT', { style: 'currency', currency: 'EUR' });\n</script>\n```\n\n#### Disabled Slider\n\nSet the boolean `disabled` attribute to prevent interaction. The component applies disabled visual tokens and clears the reported form value automatically. Do not use `disabled=\"false\"` to re-enable - remove the attribute instead.\n\n```html\n<mds-input-range name=\"soglia\" min=\"0\" max=\"100\" value=\"40\" disabled>Soglia (disabilitato)</mds-input-range>\n```\n\n#### Form Participation\n\n`<mds-input-range>` is form-associated. Place it inside a `<form>` with a `name` attribute and the selected value is submitted automatically alongside other fields.\n\n```html\n<form action=\"/impostazioni\" method=\"post\">\n <mds-input-range name=\"luminosita\" min=\"0\" max=\"100\" value=\"75\">Luminosita</mds-input-range>\n <mds-input-range name=\"contrasto\" min=\"0\" max=\"100\" value=\"50\">Contrasto</mds-input-range>\n\n <mds-button type=\"submit\" label=\"Salva impostazioni\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Hiding the Header via `::part(header)`\n\nUse `::part(header)` to hide the label-and-value header when the surrounding UI already provides that context - for example in a compact settings row where the label lives outside the component.\n\n```css\n.slider-compatto mds-input-range::part(header) {\n display: none;\n}\n```\n\n#### Styling Customization\n\n`<mds-input-range>` has no public CSS custom property: the thumb and the track take their sizes from the component and their colours from the semantic color roles ([`agents/color.md`](../../../../agents/color.md)), the progress from the accent, so themes and dark mode recolour it without overrides. Adjust the slider only through its documented `header` and `track` parts, as in the example above.\n",
|
|
17257
|
-
"3. Mistakes": "Common incorrect uses of `<mds-input-range>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Raw `<input type=\"range\">` Instead of the Component\n\nReaching for the native element bypasses the Magma-styled track, the progress fill, the labelled header, form association wiring, and the snapping logic.\n\n```html\n<!-- INCORRECT -->\n<label for=\"v\">Volume</label>\n<input type=\"range\" id=\"v\" name=\"volume\" min=\"0\" max=\"100\">\n\n<!-- CORRECT -->\n<mds-input-range name=\"volume\" min=\"0\" max=\"100\">Volume</mds-input-range>\n```\n\n#### Do Not Omit the Label Slot\n\nWithout slotted text the slider has no accessible name - screen readers cannot announce the control's purpose. Always put a meaningful text label in the default slot.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range name=\"luminosita\" min=\"0\" max=\"100\"></mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range name=\"luminosita\" min=\"0\" max=\"100\">Luminosita</mds-input-range>\n```\n\n#### Do Not Use `disabled=\"false\"` to Enable the Slider\n\n`disabled` is a boolean attribute and `mds-input-range` is form-associated: as on a native control, any value turns it on, `\"false\"` included, so this markup disables the slider. Remove the attribute entirely to enable it.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range name=\"soglia\" disabled=\"false\">Soglia</mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range name=\"soglia\">Soglia</mds-input-range>\n```\n\n#### Do Not Listen to Raw `input` / `change` Events\n\nNative events may not bubble out of shadow DOM the way you expect. Listen to `mdsInputRangeChange`, which the component emits on every committed value change.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range id=\"r\" name=\"valore\">Valore</mds-input-range>\n<script>\n document.querySelector('#r').addEventListener('change', (e) => {\n console.log(e.target.value); // unreliable across shadow DOM\n });\n</script>\n\n<!-- CORRECT -->\n<mds-input-range id=\"r\" name=\"valore\">Valore</mds-input-range>\n<script>\n document.querySelector('#r').addEventListener('mdsInputRangeChange', (e) => {\n console.log(e.detail); // numeric value, always reliable\n });\n</script>\n```\n\n#### Do Not Set `step` to Zero or a Negative Number\n\nA `step` of zero or negative is invalid: as on a native input it is ignored and the default step, `1`, applies instead, which is rarely the granularity you meant. Use a positive integer or decimal.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range name=\"q\" step=\"0\">Quantita</mds-input-range>\n<mds-input-range name=\"q\" step=\"-1\">Quantita</mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range name=\"q\" step=\"1\">Quantita</mds-input-range>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Track or Thumb\n\nThe component exposes `::part(header)` and `::part(track)` for all supported customization; it has no public CSS custom property, and the thumb and the track take their colours from the theme. Targeting internal class names via `>>>` or undocumented `::part()` names couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-input-range >>> .track-progress {\n background-color: hotpink;\n}\nmds-input-range::part(thumb) { /* \"thumb\" is not a documented part */\n border-radius: 0;\n}\n\n/* CORRECT */\nmds-input-range::part(track) { /* \"track\" is a documented part */\n opacity: 0.8;\n}\n```\n\n#### Do Not Use `formatValue` to Change the Submitted Form Value\n\n`formatValue` is purely presentational - it only changes the header display string. The submitted form value is always the raw number. Do not rely on it for data transformation.\n\n```html\n<!-- INCORRECT: expecting the form to submit the formatted string -->\n<mds-input-range id=\"p\" name=\"prezzo\">Prezzo</mds-input-range>\n<script>\n // This changes what is shown but NOT what is submitted\n document.querySelector('#p').formatValue = (v) => v + ' EUR';\n // form.submit() still sends a plain number for \"prezzo\"\n</script>\n\n<!-- CORRECT: format on the server or in a submit handler using event.detail -->\n<mds-input-range id=\"p\" name=\"prezzo\">Prezzo</mds-input-range>\n<script>\n document.querySelector('#p').formatValue = (v) =>\n v.toLocaleString('it-IT', { style: 'currency', currency: 'EUR' });\n // The display is formatted; handle raw numeric value on submit separately\n</script>\n```\n"
|
|
17489
|
+
"1. Description": "The `<mds-input-range>` web component is the Magma Design System slider control for picking a numeric value from a continuous interval, or several values on one track. It wraps a native `<input type=\"range\">` per thumb, adding a labelled header, a styled track with a live progress fill, form association, and value formatting.\n\n#### Semantic Behavior\n\n- **Form association**: Inside a `<form>` the selected number is reported under `name` with no extra wiring. A form reset brings back the value of load, thumb and progress included, or the middle of the range when the markup sets no `value`, like a native input.\n- **Value clamping and snapping**: On input the value is clamped into `[min, max]` and snapped to the nearest `step` increment, so the committed `value` is always valid even when set programmatically out of range.\n- **Decimal awareness**: The number of decimal places is derived from `step`, letting fractional steps snap correctly; as on a native input, a `step` that is not a positive number, from the start or set later, falls back to the default step, `1`.\n- **Disabled state**: Blocks interaction and clears the reported form value while disabled; enabled again, the range reports its value again. A disabled `<fieldset>` around the component does the same, as it does a native input.\n- **Emitted event**: `mdsInputRangeChange` carries the new numeric value whenever `value` actually changes.\n- **Accessibility**: The control takes its accessible name from the slotted label text; with `formatValue` it also announces the formatted value (`aria-valuetext`). The ring of the focus goes round the thumb.\n- **Default slot is the label**: The default slot holds the field's text label, rendered in the header alongside the formatted current value.\n- **Width**: The slider takes the width its container gives it, a narrow grid cell too: the track gets shorter and a label longer than the room left by the value ends in an ellipsis.\n\n#### Several Values on One Track\n\nAn [`<mds-input-range-value>`](../mds-input-range-value/AGENTS.md) child per value turns the range into a slider with a thumb per value, as an `<option>` per choice turns a `<select>` into a list: a minimum and a maximum, or the stops of a scale.\n\n- **From the first child on**: with one child or more, the values are the children's, one child included; `value` and `mdsInputRangeChange` are left out, and keep the one value of a range without children.\n- **One native input per thumb**: each thumb is a native range input, all of them stacked on the track. The native input gives the slider role, the value, the name, the focus and the drag; a component of `role=\"slider\"` elements would rewrite them, and leave the one value on another control.\n- **Neighbours bound each other**: a thumb never passes the thumbs next to it, but can reach them. The arrows move the thumb with the focus by one `step`, Page Up and Page Down by a tenth of the range, Home and End take it to its neighbours (or to `min` and `max`): the component handles these keys itself, because a native input knows only `min` and `max`.\n- **Order and limits of the markup**: the thumbs follow the values from the lowest, whatever the order of the children; each keeps the name of its own child. A value outside `min` and `max`, or off the step, is brought inside and onto the step, as a native input sanitizes it, and written back on its child; a child without a value starts in the middle.\n- **Names**: the text of the range names the group of thumbs, the text of each child names its thumb, as in the multi-thumb slider of the WAI-ARIA APG. A child without text gets the label and the position of its thumb (\"Prezzo, 1 di 2\", in the language of the page).\n- **Header**: the values in order, formatted as the one value: two are an interval joined by an en dash (\"20 - 80\" with a long dash), more a list joined by a middle dot.\n- **Fill**: from the first thumb to the last.\n- **Overlap**: a thumb is as wide as the track is tall, so two near values lie on each other: the thumb with the focus lies on top and the keys move it alone. Without the focus, a thumb held by its neighbours lies under them, so that the one on top can move.\n- **Pointer**: a thumb drags itself; a press on the track moves the nearest thumb there.\n- **Adding and removing**: adding a value is adding a child, removing one is removing it; the range watches its children, their values and their text.\n- **Form**: an entry per value under `name`, in order, as a native `<select multiple>`; a form reset gives each child back the value it had when the range first read it.\n- **Event**: `mdsInputRangeValuesChange` carries `{ values }`, in order, whenever the list changes: from a thumb, from code, as a child comes or goes, on a reset. The values of load are not a change.\n\n#### Properties & Visual Configurations\n\n- **`min` / `max` / `step`** define the permitted interval and granularity; `step` also controls how fractional values are snapped and how many decimals are preserved.\n- **`value`** is the committed numeric selection of a range without `<mds-input-range-value>` children, kept clamped and snapped - set it programmatically to move the thumb. With children, each child holds the value of its thumb.\n- **`formatValue`** is a function `(value: number) => string` for presentation only: use it to render the header value as currency, a percentage, or a unit-suffixed label without changing the underlying numeric `value`.\n\nThis component does not use the shared `variant` / `tone` ladders ([`agents/variants.md`](../../../../agents/variants.md)); it has no public CSS custom property: the thumb and the track follow the theme, and the `header` and `track` parts listed in [`AGENTS.md`](AGENTS.md) are its styling hooks.\n",
|
|
17490
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-input-range>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Slider with a Label\n\nThe minimum viable form. Put the field's text label in the default slot - it is rendered in the header and used as the accessible name for the underlying input. The default range is 0-100 with a step of 1.\n\n```html\n<mds-input-range name=\"volume\">Volume</mds-input-range>\n```\n\n#### Setting `min`, `max`, and `step`\n\nConstrain the range to a meaningful interval. Use `step` to enforce granularity - the component snaps the selected value to the nearest multiple automatically.\n\n```html\n<!-- Percentage slider, 5-point increments -->\n<mds-input-range name=\"completamento\" min=\"0\" max=\"100\" step=\"5\">Completamento (%)</mds-input-range>\n\n<!-- Temperature slider, half-degree steps -->\n<mds-input-range name=\"temperatura\" min=\"16\" max=\"30\" step=\"0.5\">Temperatura (C)</mds-input-range>\n```\n\n#### Pre-selected Value via `value`\n\nPass `value` to initialize the thumb at a specific position. The prop is reflected, so it also stays in sync when the user drags.\n\n```html\n<mds-input-range name=\"priorita\" min=\"1\" max=\"10\" value=\"7\">Priorita</mds-input-range>\n```\n\n#### Listening to `mdsInputRangeChange`\n\nThe component emits `mdsInputRangeChange` with the new numeric value in `event.detail` whenever the committed value changes. Do not listen to the raw `input` or `change` events - they may not bubble out of shadow DOM as expected.\n\n```html\n<mds-input-range id=\"rating\" name=\"valutazione\" min=\"1\" max=\"5\">Valutazione</mds-input-range>\n\n<script>\n document.querySelector('#rating').addEventListener('mdsInputRangeChange', (event) => {\n console.log('Nuovo valore:', event.detail);\n });\n</script>\n```\n\n#### Custom Value Display with `formatValue`\n\nSupply a `(value: number) => string` function to `formatValue` to change how the current value is shown in the header label - for example to add a unit suffix, format as currency, or humanize byte counts. The underlying numeric `value` is not affected.\n\n```html\n<mds-input-range id=\"prezzo\" name=\"prezzo\" min=\"0\" max=\"10000\" step=\"50\">Prezzo massimo</mds-input-range>\n\n<script>\n document.querySelector('#prezzo').formatValue = (v) =>\n v.toLocaleString('it-IT', { style: 'currency', currency: 'EUR' });\n</script>\n```\n\n#### Disabled Slider\n\nSet the boolean `disabled` attribute to prevent interaction. The component applies disabled visual tokens and clears the reported form value automatically. Do not use `disabled=\"false\"` to re-enable - remove the attribute instead.\n\n```html\n<mds-input-range name=\"soglia\" min=\"0\" max=\"100\" value=\"40\" disabled>Soglia (disabilitato)</mds-input-range>\n```\n\n#### Form Participation\n\n`<mds-input-range>` is form-associated. Place it inside a `<form>` with a `name` attribute and the selected value is submitted automatically alongside other fields.\n\n```html\n<form action=\"/impostazioni\" method=\"post\">\n <mds-input-range name=\"luminosita\" min=\"0\" max=\"100\" value=\"75\">Luminosita</mds-input-range>\n <mds-input-range name=\"contrasto\" min=\"0\" max=\"100\" value=\"50\">Contrasto</mds-input-range>\n\n <mds-button type=\"submit\" label=\"Salva impostazioni\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Several Values: an Interval\n\nPut an [`<mds-input-range-value>`](../mds-input-range-value/AGENTS.md) per value inside the range: a thumb each. The text of the range is the label of the group, the text of each value names its thumb. The header shows the two values as an interval, formatted by `formatValue` as the one value.\n\n```html\n<mds-input-range id=\"prezzo-intervallo\" min=\"0\" max=\"500\" step=\"10\" name=\"prezzo\">\n Prezzo\n <mds-input-range-value value=\"100\">Minimo</mds-input-range-value>\n <mds-input-range-value value=\"400\">Massimo</mds-input-range-value>\n</mds-input-range>\n\n<script>\n document.querySelector('#prezzo-intervallo').formatValue = (v) =>\n v.toLocaleString('it-IT', { style: 'currency', currency: 'EUR' });\n</script>\n```\n\nThe form receives one entry per value under `name`, in order: `prezzo=100&prezzo=400`, read on the server as a list, as the entries of a `<select multiple>`.\n\n#### Several Values: Listening to `mdsInputRangeValuesChange`\n\nWith values, the range emits `mdsInputRangeValuesChange`, whose `detail.values` lists them in order from the lowest. It fires whenever the list changes: a thumb moved, a value set from code, a value added or removed, a form reset.\n\n```html\n<mds-input-range id=\"scala\" min=\"1\" max=\"21\" step=\"0.5\" name=\"contrasto\">\n Scala di contrasto\n <mds-input-range-value value=\"3\"></mds-input-range-value>\n <mds-input-range-value value=\"4.5\"></mds-input-range-value>\n <mds-input-range-value value=\"7\"></mds-input-range-value>\n <mds-input-range-value value=\"12\"></mds-input-range-value>\n</mds-input-range>\n\n<script>\n document.querySelector('#scala').addEventListener('mdsInputRangeValuesChange', (event) => {\n console.log('Passi:', event.detail.values); // [3, 4.5, 7, 12]\n });\n</script>\n```\n\nThe values without text are named after the label and their position (\"Scala di contrasto, 2 di 4\"). Adding a stop is appending an `<mds-input-range-value>`, removing one is removing it.\n\n#### Hiding the Header via `::part(header)`\n\nUse `::part(header)` to hide the label-and-value header when the surrounding UI already provides that context - for example in a compact settings row where the label lives outside the component.\n\n```css\n.slider-compatto mds-input-range::part(header) {\n display: none;\n}\n```\n\n#### Styling Customization\n\n`<mds-input-range>` has no public CSS custom property: the thumb and the track take their sizes from the component and their colours from the semantic color roles ([`agents/color.md`](../../../../agents/color.md)), the progress from the accent, so themes and dark mode recolour it without overrides. Adjust the slider only through its documented `header` and `track` parts, as in the example above.\n",
|
|
17491
|
+
"3. Mistakes": "Common incorrect uses of `<mds-input-range>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use a Raw `<input type=\"range\">` Instead of the Component\n\nReaching for the native element bypasses the Magma-styled track, the progress fill, the labelled header, form association wiring, and the snapping logic.\n\n```html\n<!-- INCORRECT -->\n<label for=\"v\">Volume</label>\n<input type=\"range\" id=\"v\" name=\"volume\" min=\"0\" max=\"100\">\n\n<!-- CORRECT -->\n<mds-input-range name=\"volume\" min=\"0\" max=\"100\">Volume</mds-input-range>\n```\n\n#### Do Not Omit the Label Slot\n\nWithout slotted text the slider has no accessible name - screen readers cannot announce the control's purpose. Always put a meaningful text label in the default slot.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range name=\"luminosita\" min=\"0\" max=\"100\"></mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range name=\"luminosita\" min=\"0\" max=\"100\">Luminosita</mds-input-range>\n```\n\n#### Do Not Use `disabled=\"false\"` to Enable the Slider\n\n`disabled` is a boolean attribute and `mds-input-range` is form-associated: as on a native control, any value turns it on, `\"false\"` included, so this markup disables the slider. Remove the attribute entirely to enable it.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range name=\"soglia\" disabled=\"false\">Soglia</mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range name=\"soglia\">Soglia</mds-input-range>\n```\n\n#### Do Not Listen to Raw `input` / `change` Events\n\nNative events may not bubble out of shadow DOM the way you expect. Listen to `mdsInputRangeChange`, which the component emits on every committed value change.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range id=\"r\" name=\"valore\">Valore</mds-input-range>\n<script>\n document.querySelector('#r').addEventListener('change', (e) => {\n console.log(e.target.value); // unreliable across shadow DOM\n });\n</script>\n\n<!-- CORRECT -->\n<mds-input-range id=\"r\" name=\"valore\">Valore</mds-input-range>\n<script>\n document.querySelector('#r').addEventListener('mdsInputRangeChange', (e) => {\n console.log(e.detail); // numeric value, always reliable\n });\n</script>\n```\n\n#### Do Not Set `step` to Zero or a Negative Number\n\nA `step` of zero or negative is invalid: as on a native input it is ignored and the default step, `1`, applies instead, which is rarely the granularity you meant. Use a positive integer or decimal.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range name=\"q\" step=\"0\">Quantita</mds-input-range>\n<mds-input-range name=\"q\" step=\"-1\">Quantita</mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range name=\"q\" step=\"1\">Quantita</mds-input-range>\n```\n\n#### Do Not Put Several Ranges Side by Side for One Interval\n\nTwo ranges for a minimum and a maximum let the minimum pass the maximum, and give the form two names. Put both values on one range.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range name=\"prezzo-min\" value=\"100\">Prezzo minimo</mds-input-range>\n<mds-input-range name=\"prezzo-max\" value=\"400\">Prezzo massimo</mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range name=\"prezzo\">\n Prezzo\n <mds-input-range-value value=\"100\">Minimo</mds-input-range-value>\n <mds-input-range-value value=\"400\">Massimo</mds-input-range-value>\n</mds-input-range>\n```\n\n#### Do Not Set `value` on a Range with Values\n\nWith `<mds-input-range-value>` children, the values are theirs: `value` of the range and `mdsInputRangeChange` are left out. Set and read the values on the children, or listen to `mdsInputRangeValuesChange`.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range value=\"20\">\n Prezzo\n <mds-input-range-value>Minimo</mds-input-range-value>\n <mds-input-range-value>Massimo</mds-input-range-value>\n</mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range>\n Prezzo\n <mds-input-range-value value=\"20\">Minimo</mds-input-range-value>\n <mds-input-range-value value=\"80\">Massimo</mds-input-range-value>\n</mds-input-range>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Track or Thumb\n\nThe component exposes `::part(header)` and `::part(track)` for all supported customization; it has no public CSS custom property, and the thumb and the track take their colours from the theme. Targeting internal class names via `>>>` or undocumented `::part()` names couples your code to the implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-input-range >>> .track-progress {\n background-color: hotpink;\n}\nmds-input-range::part(thumb) { /* \"thumb\" is not a documented part */\n border-radius: 0;\n}\n\n/* CORRECT */\nmds-input-range::part(track) { /* \"track\" is a documented part */\n opacity: 0.8;\n}\n```\n\n#### Do Not Use `formatValue` to Change the Submitted Form Value\n\n`formatValue` is purely presentational - it only changes the header display string. The submitted form value is always the raw number. Do not rely on it for data transformation.\n\n```html\n<!-- INCORRECT: expecting the form to submit the formatted string -->\n<mds-input-range id=\"p\" name=\"prezzo\">Prezzo</mds-input-range>\n<script>\n // This changes what is shown but NOT what is submitted\n document.querySelector('#p').formatValue = (v) => v + ' EUR';\n // form.submit() still sends a plain number for \"prezzo\"\n</script>\n\n<!-- CORRECT: format on the server or in a submit handler using event.detail -->\n<mds-input-range id=\"p\" name=\"prezzo\">Prezzo</mds-input-range>\n<script>\n document.querySelector('#p').formatValue = (v) =>\n v.toLocaleString('it-IT', { style: 'currency', currency: 'EUR' });\n // The display is formatted; handle raw numeric value on submit separately\n</script>\n```\n"
|
|
17258
17492
|
},
|
|
17259
17493
|
"props": [
|
|
17260
17494
|
{
|
|
@@ -17432,7 +17666,7 @@
|
|
|
17432
17666
|
"mutable": true,
|
|
17433
17667
|
"attr": "value",
|
|
17434
17668
|
"reflectToAttr": true,
|
|
17435
|
-
"docs": "The value attribute contains a number which contains a representation of the selected number
|
|
17669
|
+
"docs": "The value attribute contains a number which contains a representation of the selected number.\nIt holds the one value of a range without `mds-input-range-value` children: with children the\nvalues are theirs, and this one is left out",
|
|
17436
17670
|
"docsTags": [],
|
|
17437
17671
|
"values": [
|
|
17438
17672
|
{
|
|
@@ -17458,7 +17692,28 @@
|
|
|
17458
17692
|
},
|
|
17459
17693
|
"cancelable": true,
|
|
17460
17694
|
"composed": true,
|
|
17461
|
-
"docs": "Emits when the input range is changed",
|
|
17695
|
+
"docs": "Emits when the input range is changed: the value of a range without\n`mds-input-range-value` children",
|
|
17696
|
+
"docsTags": []
|
|
17697
|
+
},
|
|
17698
|
+
{
|
|
17699
|
+
"event": "mdsInputRangeValuesChange",
|
|
17700
|
+
"detail": "MdsInputRangeValuesEventDetail",
|
|
17701
|
+
"bubbles": true,
|
|
17702
|
+
"complexType": {
|
|
17703
|
+
"original": "MdsInputRangeValuesEventDetail",
|
|
17704
|
+
"resolved": "MdsInputRangeValuesEventDetail",
|
|
17705
|
+
"references": {
|
|
17706
|
+
"MdsInputRangeValuesEventDetail": {
|
|
17707
|
+
"location": "import",
|
|
17708
|
+
"path": "./meta/event-detail",
|
|
17709
|
+
"id": "src/components/mds-input-range/meta/event-detail.ts::MdsInputRangeValuesEventDetail",
|
|
17710
|
+
"referenceLocation": "MdsInputRangeValuesEventDetail"
|
|
17711
|
+
}
|
|
17712
|
+
}
|
|
17713
|
+
},
|
|
17714
|
+
"cancelable": true,
|
|
17715
|
+
"composed": true,
|
|
17716
|
+
"docs": "Emits when the values of a range with `mds-input-range-value` children change: from a thumb,\nfrom code, as a child comes or goes, or on a form reset. `values` holds them in order, from\nthe lowest. The values of load are not a change",
|
|
17462
17717
|
"docsTags": []
|
|
17463
17718
|
}
|
|
17464
17719
|
],
|
|
@@ -17522,7 +17777,7 @@
|
|
|
17522
17777
|
"slots": [
|
|
17523
17778
|
{
|
|
17524
17779
|
"name": "",
|
|
17525
|
-
"docs": "
|
|
17780
|
+
"docs": "The label of the range, as text. Add an `mds-input-range-value` per value to hold\nseveral values, a thumb each, on one track"
|
|
17526
17781
|
}
|
|
17527
17782
|
],
|
|
17528
17783
|
"parts": [
|
|
@@ -17547,6 +17802,72 @@
|
|
|
17547
17802
|
},
|
|
17548
17803
|
"storybook": "form-range--docs"
|
|
17549
17804
|
},
|
|
17805
|
+
{
|
|
17806
|
+
"filePath": "src/components/mds-input-range-value/mds-input-range-value.tsx",
|
|
17807
|
+
"encapsulation": "shadow",
|
|
17808
|
+
"tag": "mds-input-range-value",
|
|
17809
|
+
"readme": "# mds-input-range-value\n\n\n",
|
|
17810
|
+
"docs": "One value of an `mds-input-range` that holds several, as an `<option>` is one choice of a\n`<select>`: the range draws a thumb for it, and its text names that thumb. It draws nothing\nitself. Adding or removing a value is adding or removing one of these elements: the range\nwatches its children.",
|
|
17811
|
+
"docsTags": [
|
|
17812
|
+
{
|
|
17813
|
+
"name": "slot",
|
|
17814
|
+
"text": "- The name of the value, as text (\"Minimo\", \"Massimo\"): the accessible name of its thumb.\nWithout text the thumb is named after the label of the range and its position (\"Prezzo, 1 di 2\")"
|
|
17815
|
+
},
|
|
17816
|
+
{
|
|
17817
|
+
"name": "parent",
|
|
17818
|
+
"text": "mds-input-range"
|
|
17819
|
+
}
|
|
17820
|
+
],
|
|
17821
|
+
"usage": {
|
|
17822
|
+
"1. Description": "The `<mds-input-range-value>` web component is one value of a [`<mds-input-range>`](../mds-input-range/AGENTS.md) that holds several values on one track, as an `<option>` is one choice of a `<select>`. The range draws a thumb for each of its `<mds-input-range-value>` children; the child itself draws nothing.\n\n#### Semantic Behavior\n\n- **Compound child only**: it works only as a direct child of `<mds-input-range>`. Outside a range it is hidden and does nothing.\n- **One child, one thumb**: adding a value is adding a child, removing one is removing its child. The range watches its children, their values and their text.\n- **The text names the thumb**: the text of the child is the accessible name of its thumb (\"Minimo\", \"Massimo\"), as each thumb of the multi-thumb slider of the WAI-ARIA APG. A child without text gets a name made of the label of the range and its position (\"Prezzo, 1 di 2\", in the language of the page).\n- **The range keeps the value valid**: it brings a value outside `min` and `max`, or off the `step`, inside the range and onto the step, as a native range input does, and writes it back here. A child without a value starts in the middle of the range.\n- **The order is the order of the values**: the thumbs follow their values from the lowest, whatever the order of the children in the markup; each keeps the name of its own child.\n- **The value follows the thumb**: as the thumb moves, the range writes its value on `value`, which is reflected. Setting `value` moves the thumb.\n\n#### Properties & Visual Configurations\n\nThe only prop is `value`, the number of the thumb. The thumb is styled by its range: the child has no `variant` / `tone` ([`agents/variants.md`](../../../../agents/variants.md)), no part and no public CSS custom property.\n",
|
|
17823
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-input-range-value>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### An Interval: Two Values\n\nThe canonical form: a minimum and a maximum on one track. The text of the range is its label, the text of each value names its thumb.\n\n```html\n<mds-input-range min=\"0\" max=\"500\" step=\"10\" name=\"prezzo\">\n Prezzo\n <mds-input-range-value value=\"100\">Minimo</mds-input-range-value>\n <mds-input-range-value value=\"400\">Massimo</mds-input-range-value>\n</mds-input-range>\n```\n\n#### A Scale of Stops\n\nMore than two values: each stops at its neighbours, which it can reach but not pass. The header lists them, separated by a middle dot.\n\n```html\n<mds-input-range min=\"1\" max=\"21\" step=\"0.5\" name=\"contrasto\">\n Scala di contrasto\n <mds-input-range-value value=\"3\">Passo 1</mds-input-range-value>\n <mds-input-range-value value=\"4.5\">Passo 2</mds-input-range-value>\n <mds-input-range-value value=\"7\">Passo 3</mds-input-range-value>\n <mds-input-range-value value=\"12\">Passo 4</mds-input-range-value>\n</mds-input-range>\n```\n\n#### Adding and Removing a Value\n\nA value is an element: append a child to add a thumb, remove it to take the thumb away. The range emits `mdsInputRangeValuesChange` with the new list.\n\n```html\n<mds-input-range id=\"scala\" min=\"0\" max=\"100\" name=\"passi\">\n Passi\n <mds-input-range-value value=\"20\"></mds-input-range-value>\n <mds-input-range-value value=\"80\"></mds-input-range-value>\n</mds-input-range>\n\n<script>\n const scala = document.querySelector('#scala');\n const passo = document.createElement('mds-input-range-value');\n passo.value = 50;\n scala.append(passo); // a third thumb at 50\n passo.remove(); // back to two\n</script>\n```\n\n#### Reading and Setting a Value\n\n`value` follows its thumb, so the children are where the page reads the values; setting `value` moves the thumb, within its neighbours.\n\n```js\nconst [minimo, massimo] = document.querySelectorAll('#prezzo mds-input-range-value');\nconsole.log(minimo.value, massimo.value);\nmassimo.value = 300;\n```\n",
|
|
17824
|
+
"3. Mistakes": "Common incorrect uses of `<mds-input-range-value>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use It Outside `<mds-input-range>`\n\nA value draws nothing: only its range draws its thumb.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range-value value=\"20\">Minimo</mds-input-range-value>\n\n<!-- CORRECT -->\n<mds-input-range min=\"0\" max=\"100\">\n Prezzo\n <mds-input-range-value value=\"20\">Minimo</mds-input-range-value>\n</mds-input-range>\n```\n\n#### Do Not Put the Label of the Range in a Value\n\nThe text of the range is its label, the text of a value names its own thumb. A value that carries the label leaves the range unnamed and names one thumb after the whole group.\n\n```html\n<!-- INCORRECT -->\n<mds-input-range>\n <mds-input-range-value value=\"20\">Prezzo</mds-input-range-value>\n <mds-input-range-value value=\"80\"></mds-input-range-value>\n</mds-input-range>\n\n<!-- CORRECT -->\n<mds-input-range>\n Prezzo\n <mds-input-range-value value=\"20\">Minimo</mds-input-range-value>\n <mds-input-range-value value=\"80\">Massimo</mds-input-range-value>\n</mds-input-range>\n```\n\n#### Do Not Read the Values from `value` of the Range\n\nWith values, `value` and `mdsInputRangeChange` of the range are left out: they hold the one value of a range without children. Read the children, `mdsInputRangeValuesChange` or the form.\n\n```js\n// INCORRECT\nrange.addEventListener('mdsInputRangeChange', (e) => console.log(e.detail));\n\n// CORRECT\nrange.addEventListener('mdsInputRangeValuesChange', (e) => console.log(e.detail.values));\n```\n"
|
|
17825
|
+
},
|
|
17826
|
+
"props": [
|
|
17827
|
+
{
|
|
17828
|
+
"name": "value",
|
|
17829
|
+
"type": "number | undefined",
|
|
17830
|
+
"complexType": {
|
|
17831
|
+
"original": "number",
|
|
17832
|
+
"resolved": "number | undefined",
|
|
17833
|
+
"references": {}
|
|
17834
|
+
},
|
|
17835
|
+
"mutable": true,
|
|
17836
|
+
"attr": "value",
|
|
17837
|
+
"reflectToAttr": true,
|
|
17838
|
+
"docs": "The value of the thumb. The range keeps it inside its `min` and `max`, on its `step` and\nbetween the values next to it, and writes it here as the thumb moves; set it to move the\nthumb. Without a value the thumb starts in the middle of the range, as a native range input",
|
|
17839
|
+
"docsTags": [],
|
|
17840
|
+
"values": [
|
|
17841
|
+
{
|
|
17842
|
+
"type": "number"
|
|
17843
|
+
},
|
|
17844
|
+
{
|
|
17845
|
+
"type": "undefined"
|
|
17846
|
+
}
|
|
17847
|
+
],
|
|
17848
|
+
"optional": true,
|
|
17849
|
+
"required": false,
|
|
17850
|
+
"getter": false,
|
|
17851
|
+
"setter": false
|
|
17852
|
+
}
|
|
17853
|
+
],
|
|
17854
|
+
"methods": [],
|
|
17855
|
+
"events": [],
|
|
17856
|
+
"listeners": [],
|
|
17857
|
+
"styles": [],
|
|
17858
|
+
"slots": [
|
|
17859
|
+
{
|
|
17860
|
+
"name": "",
|
|
17861
|
+
"docs": "The name of the value, as text (\"Minimo\", \"Massimo\"): the accessible name of its thumb.\nWithout text the thumb is named after the label of the range and its position (\"Prezzo, 1 di 2\")"
|
|
17862
|
+
}
|
|
17863
|
+
],
|
|
17864
|
+
"parts": [],
|
|
17865
|
+
"states": [],
|
|
17866
|
+
"dependents": [],
|
|
17867
|
+
"dependencies": [],
|
|
17868
|
+
"dependencyGraph": {},
|
|
17869
|
+
"storybook": "ui-forms-range-value--docs"
|
|
17870
|
+
},
|
|
17550
17871
|
{
|
|
17551
17872
|
"filePath": "src/components/mds-input-select/mds-input-select.tsx",
|
|
17552
17873
|
"encapsulation": "shadow",
|
|
@@ -17572,7 +17893,7 @@
|
|
|
17572
17893
|
}
|
|
17573
17894
|
],
|
|
17574
17895
|
"usage": {
|
|
17575
|
-
"1. Description": "The `<mds-input-select>` web component is the Magma Design System single- and multi-choice dropdown control. It wraps a native `<select>` element, adding form association, accessible status feedback, and themed chrome while accepting plain `<option>` elements through its default slot.\n\n#### Semantic Behavior\n\n- **Native select wrapping**: It renders a real `<select>` (exposed as the `select` part) so keyboard, type-ahead, and platform option lists work natively; the host owns theming and status only.\n- **Slotted options**: The default slot accepts `<option>` (and `<optgroup>`) markup; the current selection re-syncs whenever the slotted content changes.\n- **Form association**: The selection is pushed to the host form: a single select submits its `value`, a `multiple` one an entry per selected option under `name`, as a native select. A form reset brings back the selection of load, like a native select: the options the markup marks `selected` (or the placeholder), with the `value` of load on top. Toggling `disabled` removes the value from the submitted form data.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **Form validity**: A `required` select left empty is reported to the form as a native one: it matches `:invalid` and stops the submit, with a message in the page language. A disabled select is left out, and `novalidate` on the `<form>` turns the check off.\n- **Value syncing**: Changing the selection (by user input, the `setValue()` method, or the prop) emits `mdsInputSelectChange` with `{ value, values }` in `detail`: `value` is the first selected option as a string, `values` the values of every selected option, the placeholder left out. Like a native `<select>`, it is not emitted on load: the selection the component starts with reaches the form, not the event. A `value` set by code selects its `<option>` alone, as `select.value` does, and a value cleared by code goes back to the placeholder.\n- **Placeholder option**: When `placeholder` is set, a leading empty-value `<option>` is injected as the first entry; if `required` is set that placeholder is disabled so it cannot be re-selected after a valid choice.\n- **Default selection fallback**: With no explicit value, the options the markup marks `selected` become the selection; without them, the placeholder or, with no placeholder, the first option of a single select. A `defaultValue` seeds `value` at load.\n- **Status tip**: A status tip surfaces verbose state - a disabled notice, and for required fields a `required` / `required-success` message that expands while the control has focus.\n\n#### Properties & Visual Configurations\n\nThe `variant` prop applies a status appearance drawn from the shared status ladder in [`agents/variants.md`](../../../../agents/variants.md) - use it to reflect validation outcome (`'error'`, `'success'`, `'warning'`, `'info'`) rather than decorative styling. This component exposes no separate `tone` prop.\n\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner arrow scale with it.\n\n#### Other behavioral props\n\n- **`multiple`** turns the control into a multi-select list box: the form gets an entry per selected option and `values` in the `mdsInputSelectChange` detail lists them all, while `value` holds the first one, as `select.value` does. **`rows`** sets how many option rows are visible at once, as the `size` of a native `<select>`: above `1` it shows a list box even without `multiple`. A number in `size`, the row count it used to set, still works as `rows` but warns: it is deprecated and goes in the next major.\n- **`defaultValue`** is the initial selection used to seed the value at load (notably for the React wrapper), distinct from the live `value` that reflects the current choice.\n- **`required`** both enforces a non-empty submission and locks the placeholder option so the empty entry cannot be chosen again.\n",
|
|
17896
|
+
"1. Description": "The `<mds-input-select>` web component is the Magma Design System single- and multi-choice dropdown control. It wraps a native `<select>` element, adding form association, accessible status feedback, and themed chrome while accepting plain `<option>` elements through its default slot.\n\n#### Semantic Behavior\n\n- **Native select wrapping**: It renders a real `<select>` (exposed as the `select` part) so keyboard, type-ahead, and platform option lists work natively; the host owns theming and status only.\n- **Slotted options**: The default slot accepts `<option>` (and `<optgroup>`) markup; the current selection re-syncs whenever the slotted content changes.\n- **Form association**: The selection is pushed to the host form: a single select submits its `value`, a `multiple` one an entry per selected option under `name`, as a native select. A form reset brings back the selection of load, like a native select: the options the markup marks `selected` (or the placeholder), with the `value` of load on top. Toggling `disabled` removes the value from the submitted form data.\n- **Disabled fieldset**: A disabled `<fieldset>` around the component disables it as `disabled` does, like a native control: it cannot be changed and its value is left out of the form, until the fieldset is enabled.\n- **Form validity**: A `required` select left empty is reported to the form as a native one: it matches `:invalid` and stops the submit, with a message in the page language. A disabled select is left out, and `novalidate` on the `<form>` turns the check off.\n- **Value syncing**: Changing the selection (by user input, the `setValue()` method, or the prop) emits `mdsInputSelectChange` with `{ value, values }` in `detail`: `value` is the first selected option as a string, `values` the values of every selected option, the placeholder left out. Like a native `<select>`, it is not emitted on load: the selection the component starts with reaches the form, not the event. A `value` set by code selects its `<option>` alone, as `select.value` does, and a value cleared by code goes back to the placeholder.\n- **Placeholder option**: When `placeholder` is set, a leading empty-value `<option>` is injected as the first entry; if `required` is set that placeholder is disabled so it cannot be re-selected after a valid choice.\n- **Default selection fallback**: With no explicit value, the options the markup marks `selected` become the selection; without them, the placeholder or, with no placeholder, the first option of a single select. A `defaultValue` seeds `value` at load.\n- **Status tip**: A status tip surfaces verbose state - a disabled notice, and for required fields a `required` / `required-success` message that expands while the control has focus. It stands on the top border of the field, half outside, clear of its rounded corner, and stays there while the control has the focus, as on `mds-input`: the arrow keeps its place.\n\n#### Properties & Visual Configurations\n\nThe `variant` prop applies a status appearance drawn from the shared status ladder in [`agents/variants.md`](../../../../agents/variants.md) - use it to reflect validation outcome (`'error'`, `'success'`, `'warning'`, `'info'`) rather than decorative styling. This component exposes no separate `tone` prop.\n\n- **`size`** sets the height of the field, the same as [`<mds-button>`](../mds-button/AGENTS.md): `sm` 28px, `md` 36px, `lg` 48px (default). Match it to the buttons next to the field, or go smaller in dense layouts (filter bars, table toolbars); the text style stays the same, the padding and the inner arrow scale with it.\n\n#### Other behavioral props\n\n- **`multiple`** turns the control into a multi-select list box: the form gets an entry per selected option and `values` in the `mdsInputSelectChange` detail lists them all, while `value` holds the first one, as `select.value` does. **`rows`** sets how many option rows are visible at once, as the `size` of a native `<select>`: above `1` it shows a list box even without `multiple`. A number in `size`, the row count it used to set, still works as `rows` but warns: it is deprecated and goes in the next major.\n- **`defaultValue`** is the initial selection used to seed the value at load (notably for the React wrapper), distinct from the live `value` that reflects the current choice.\n- **`required`** both enforces a non-empty submission and locks the placeholder option so the empty entry cannot be chosen again.\n",
|
|
17576
17897
|
"2. Examples": "Correct and idiomatic ways to use the `<mds-input-select>` component, ordered from most common to most specialized. The examples assume a working knowledge of the variant / tone ladders documented in [`agents/variants.md`](../../../../agents/variants.md) and the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Select with Placeholder\n\nThe canonical form. Slot plain `<option>` elements as direct children. Set `placeholder` to inject a leading empty-value entry that prompts the user before a choice is made.\n\n```html\n<mds-input-select name=\"categoria\" placeholder=\"Seleziona una categoria...\">\n <option value=\"news\">Notizie</option>\n <option value=\"eventi\">Eventi</option>\n <option value=\"avvisi\">Avvisi</option>\n</mds-input-select>\n```\n\n#### Required Select Inside a Form\n\nAdding `required` enforces a non-empty submission - an empty select stops the submit like a native one - and disables the placeholder option once a valid choice exists, so users cannot revert to the empty entry. Place the component inside a `<form>` - it is form-associated and submits natively.\n\n```html\n<form action=\"/salva\" method=\"post\">\n <mds-input-select name=\"regione\" required placeholder=\"Scegli la regione...\">\n <option value=\"lombardia\">Lombardia</option>\n <option value=\"veneto\">Veneto</option>\n <option value=\"toscana\">Toscana</option>\n </mds-input-select>\n <mds-button type=\"submit\" label=\"Invia\" variant=\"primary\" tone=\"strong\"></mds-button>\n</form>\n```\n\n#### Pre-selected Value via `value`\n\nPass `value` to open the component with a specific option already chosen. The matching `<option>` is marked selected automatically. Use `default-value` instead when the initial selection is set once at load and you do not need live two-way binding (notably in the React wrapper).\n\n```html\n<!-- Live controlled value -->\n<mds-input-select name=\"priorita\" value=\"alta\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n\n<!-- Initial seed value for React / SSR -->\n<mds-input-select name=\"priorita\" default-value=\"media\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n```\n\n#### Listening to Value Changes\n\nListen to `mdsInputSelectChange` - do not rely on the native `change` event, which may not bubble out of shadow DOM reliably. The event detail carries the chosen value as a string in `value`, and the values of every selected option in `values`.\n\n```html\n<mds-input-select id=\"stato-pratica\" name=\"stato\" placeholder=\"Seleziona stato...\">\n <option value=\"bozza\">Bozza</option>\n <option value=\"in-lavorazione\">In lavorazione</option>\n <option value=\"chiusa\">Chiusa</option>\n</mds-input-select>\n\n<script>\n document.getElementById('stato-pratica')\n .addEventListener('mdsInputSelectChange', (event) => {\n console.log('Nuovo stato:', event.detail.value);\n });\n</script>\n```\n\n#### Programmatic Value via `setValue()`\n\nUse the `setValue()` async method when you need to change the selection from JavaScript after the component has rendered - for example when a related control resets the form state.\n\n```html\n<mds-input-select id=\"provincia\" name=\"provincia\" placeholder=\"Seleziona provincia...\">\n <option value=\"MI\">Milano</option>\n <option value=\"RM\">Roma</option>\n <option value=\"TO\">Torino</option>\n</mds-input-select>\n\n<script>\n async function resetSelezione() {\n const el = document.getElementById('provincia');\n await el.setValue('MI');\n }\n</script>\n```\n\n#### Disabled State\n\nSet `disabled` as a boolean attribute to block interaction and remove the value from the submitted form data. A status tip is shown automatically while the component is disabled.\n\n```html\n<mds-input-select name=\"tipo-contratto\" disabled placeholder=\"Non disponibile\">\n <option value=\"td\">Tempo determinato</option>\n <option value=\"ti\">Tempo indeterminato</option>\n</mds-input-select>\n```\n\n#### Multi-select List Box\n\n`multiple` switches the component to a scrollable list that allows zero or more simultaneous selections. Use `rows` to control how many rows are visible without scrolling (`size` sets the height of the field). Mark the options to preselect with `selected`, as in a native `<select multiple>`. The form submits an entry per selected option under `name`, and `values` in the `mdsInputSelectChange` detail lists them all; `value` holds only the first one, as `select.value` does.\n\n```html\n<mds-input-select name=\"competenze\" multiple rows=\"4\">\n <option value=\"js\" selected>JavaScript</option>\n <option value=\"ts\" selected>TypeScript</option>\n <option value=\"css\">CSS</option>\n <option value=\"html\">HTML</option>\n <option value=\"react\">React</option>\n</mds-input-select>\n```\n\n#### Grouped Options via `<optgroup>`\n\nThe default slot also accepts `<optgroup>` elements. Use them to group related options under a visible label.\n\n```html\n<mds-input-select name=\"comune\" placeholder=\"Seleziona comune...\">\n <optgroup label=\"Lombardia\">\n <option value=\"MI\">Milano</option>\n <option value=\"BS\">Brescia</option>\n </optgroup>\n <optgroup label=\"Veneto\">\n <option value=\"VE\">Venezia</option>\n <option value=\"VR\">Verona</option>\n </optgroup>\n</mds-input-select>\n```\n\n#### Variant for Validation Feedback\n\nSet `variant` to one of the status values (`error`, `success`, `warning`, `info`) to communicate the validation outcome visually. Use this after a form submission or inline validation, not as decorative styling.\n\n```html\n<!-- Errore di validazione -->\n<mds-input-select name=\"tipologia\" variant=\"error\" required placeholder=\"Seleziona tipologia...\">\n <option value=\"A\">Tipo A</option>\n <option value=\"B\">Tipo B</option>\n</mds-input-select>\n\n<!-- Selezione valida confermata -->\n<mds-input-select name=\"tipologia\" variant=\"success\" value=\"A\">\n <option value=\"A\">Tipo A</option>\n <option value=\"B\">Tipo B</option>\n</mds-input-select>\n```\n\n#### Styling Customization\n\nCustomize the component only through its public `--mds-input-select-*` CSS custom properties. Set them on the host or a parent selector; use the semantic color roles ([`agents/color.md`](../../../../agents/color.md)) so dark mode and high-contrast modes continue to work correctly. `--mds-input-select-variant-color-rgb` takes a bare RGB triplet (`var(--magma-<role>)`, no `rgb()`); `--mds-input-select-ring` and `--mds-input-select-shadow` take a box-shadow, its color written as `rgb(var(--magma-<role>))`. `--mds-input-select-ring` is the ring at rest: on hover and focus the select draws its own 3px ring in the variant color, so the focus stays visible whatever the ring at rest, in dark mode and with more contrast too; change its color through `--mds-input-select-variant-color-rgb`.\n\n```css\n.sidebar-filter mds-input-select {\n --mds-input-select-variant-color-rgb: var(--magma-accent-emphasis);\n --mds-input-select-ring: 0 0 0 2px rgb(var(--magma-accent-emphasis) / 0.8);\n}\n```\n",
|
|
17577
17898
|
"3. Mistakes": "Common incorrect uses of `<mds-input-select>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Slot Non-Option Elements\n\nThe default slot is reserved for `<option>` and `<optgroup>` elements. The component clones slot children into the inner `<select>`; any other element is copied verbatim and makes the native select malformed.\n\n```html\n<!-- INCORRECT -->\n<mds-input-select name=\"categoria\">\n <div class=\"option-group\">\n <span>Notizie</span>\n <span>Eventi</span>\n </div>\n</mds-input-select>\n\n<!-- CORRECT -->\n<mds-input-select name=\"categoria\" placeholder=\"Seleziona...\">\n <option value=\"news\">Notizie</option>\n <option value=\"eventi\">Eventi</option>\n</mds-input-select>\n```\n\n#### Do Not Listen to the Native `change` Event\n\n`<mds-input-select>` wraps a shadow-DOM `<select>`; the native `change` event does not bubble out of shadow DOM reliably. Always listen to the documented `mdsInputSelectChange` custom event instead.\n\n```html\n<!-- INCORRECT -->\n<mds-input-select id=\"sel\" name=\"tipo\"></mds-input-select>\n<script>\n document.getElementById('sel').addEventListener('change', (e) => {\n console.log(e.target.value); // may be undefined or stale\n });\n</script>\n\n<!-- CORRECT -->\n<mds-input-select id=\"sel\" name=\"tipo\"></mds-input-select>\n<script>\n document.getElementById('sel').addEventListener('mdsInputSelectChange', (e) => {\n console.log(e.detail.value);\n });\n</script>\n```\n\n#### Do Not Use `variant` for Decorative Styling\n\n`variant` maps to `ThemeStatusVariantType` (`error`, `success`, `warning`, `info`). It is meant to communicate a validation outcome, not to apply a brand color. Using a status variant to make the component visually match a section's color theme misleads users about the control's validation state.\n\n```html\n<!-- INCORRECT - using 'info' just for a blue accent -->\n<mds-input-select name=\"argomento\" variant=\"info\">\n <option value=\"A\">Argomento A</option>\n</mds-input-select>\n\n<!-- CORRECT - set variant only to reflect real validation state -->\n<mds-input-select name=\"argomento\" variant=\"error\" required placeholder=\"Obbligatorio\">\n <option value=\"A\">Argomento A</option>\n</mds-input-select>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Inner `<select>`\n\nThe supported customization surface is the public `--mds-input-select-*` CSS custom properties and the two shadow parts (`select`, `tip-top`). Targeting internal elements with `>>>` or undocumented selectors couples your code to the implementation and breaks on minor releases.\n\n```css\n/* INCORRECT */\nmds-input-select >>> select {\n font-size: 1rem;\n border: 2px solid red;\n}\n\n/* CORRECT */\nmds-input-select {\n --mds-input-select-ring: 0 0 0 2px rgb(var(--magma-danger-emphasis));\n --mds-input-select-variant-color-rgb: var(--magma-danger-emphasis);\n}\nmds-input-select::part(select) {\n font-size: 1rem;\n}\n```\n\n#### Do Not Set `placeholder` When You Need a Real Default Selection\n\n`placeholder` injects an empty-value leading option that disappears from valid choices once `required` is set. If you want the component to open with a specific option pre-selected, use `value` or `default-value` instead.\n\n```html\n<!-- INCORRECT - a real value supplied as placeholder text -->\n<mds-input-select name=\"priorita\" placeholder=\"Media\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n\n<!-- CORRECT - use value to pre-select a real option -->\n<mds-input-select name=\"priorita\" value=\"media\">\n <option value=\"bassa\">Bassa</option>\n <option value=\"media\">Media</option>\n <option value=\"alta\">Alta</option>\n</mds-input-select>\n```\n\n#### Do Not Replace with a Raw `<select>`\n\n`<mds-input-select>` provides theming, accessible status tips, form-reset integration, and dark/high-contrast support. Reaching for a plain `<select>` bypasses all of that and breaks visual consistency across themes.\n\n```html\n<!-- INCORRECT -->\n<select name=\"categoria\" class=\"form-select\">\n <option value=\"\">Seleziona...</option>\n <option value=\"A\">Categoria A</option>\n</select>\n\n<!-- CORRECT -->\n<mds-input-select name=\"categoria\" placeholder=\"Seleziona...\">\n <option value=\"A\">Categoria A</option>\n</mds-input-select>\n```\n"
|
|
17578
17899
|
},
|
|
@@ -18833,8 +19154,8 @@
|
|
|
18833
19154
|
}
|
|
18834
19155
|
],
|
|
18835
19156
|
"usage": {
|
|
18836
|
-
"1. Description": "The `<mds-input-tip>` web component is the floating helper container of the Magma Design System input family: it overlays an input field and carries supplementary content (slotted `mds-input-tip-item` chips: status labels, hints, counters) that slides into place when the field becomes active. It is a presentational compound child positioned against its parent input rather than a standalone control.\n\n#### Semantic Behavior\n\n- **Floating overlay**: The tip floats over the parent input's edge without intercepting interaction (`pointer-events: none`, which `mds-input-tip-item` keeps too).\n- **Active expansion**: Setting `active` slides
|
|
18837
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-input-tip>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n`<mds-input-tip>` is an internal compound child used inside [`mds-input`](../mds-input/AGENTS.md), [`mds-input-date`](../mds-input-date/AGENTS.md), and [`mds-input-select`](../mds-input-select/AGENTS.md). It is not meant for standalone use. The patterns below show what the parent components render internally, which is useful when building a custom input wrapper that needs the same behavior.\n\n#### Status Chips Above the Field (position=\"top\")\n\nPosition the tip
|
|
19157
|
+
"1. Description": "The `<mds-input-tip>` web component is the floating helper container of the Magma Design System input family: it overlays an input field and carries supplementary content (slotted `mds-input-tip-item` chips: status labels, hints, counters) that slides into place when the field becomes active. It is a presentational compound child positioned against its parent input rather than a standalone control.\n\n#### Semantic Behavior\n\n- **Floating overlay**: The tip floats over the parent input's edge without intercepting interaction (`pointer-events: none`, which `mds-input-tip-item` keeps too).\n- **Active expansion**: Setting `active` slides a bottom tip onto the edge of the input; clearing it collapses the tip back flush with the input. A top tip stays where it stands, on the top border. It does not expand the items: each `mds-input-tip-item` shows its text only when its own `expanded` is set.\n- **On the top border**: A top tip stands on the top border of its field, half outside, so that it never covers the button at the end of the field. It keeps clear of the rounded corner by the radius of the field, which the field passes down to it, plus a margin, and sits on the straight part of the border.\n- **Empty collapse**: When the host has no slotted content it is hidden entirely, so an unused tip occupies no space.\n- **Default slot is content**: The single default slot carries the tip's arbitrary children; there are no named slots, events, form association, or focus management of its own.\n\n#### Properties & Visual Configurations\n\n- **`active`** drives the expanded vs. collapsed state and is normally toggled by the parent input in response to focus, not set manually.\n- **`position`** selects which edge of the input the tip anchors to: `'top'` (default) stands on the top border of the field, half outside, and stays there on focus; `'bottom'` sits inside the bottom edge and slides onto it when `active`.\n",
|
|
19158
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-input-tip>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n`<mds-input-tip>` is an internal compound child used inside [`mds-input`](../mds-input/AGENTS.md), [`mds-input-date`](../mds-input-date/AGENTS.md), and [`mds-input-select`](../mds-input-select/AGENTS.md). It is not meant for standalone use. The patterns below show what the parent components render internally, which is useful when building a custom input wrapper that needs the same behavior.\n\n#### Status Chips Above the Field (position=\"top\")\n\nPosition the tip on the top border of the input with `position=\"top\"` (the default), half outside, where it never covers the button at the end of the field. Slot [`mds-input-tip-item`](../mds-input-tip-item/AGENTS.md) children for each status badge to show. The parent inputs pass down the radius of their field, so that the tip keeps clear of its rounded corner. The top tip stays on the border when the field is focused; each item shows its label only when its own `expanded` is set, which the parent inputs set together with `active`.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"top\" active>\n <mds-input-tip-item variant=\"required\" expanded></mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" placeholder=\"Campo obbligatorio\" />\n</div>\n```\n\n#### Hint and Counter Below the Field (position=\"bottom\")\n\nUse `position=\"bottom\"` to anchor the tip below the input. This is the canonical placement for inline helper text and character-count feedback.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"bottom\" active>\n <mds-input-tip-item variant=\"text\" expanded>\n Inserisci almeno 8 caratteri\n </mds-input-tip-item>\n <mds-input-tip-item variant=\"count-incomplete\" expanded>\n 3 / 8\n </mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" />\n</div>\n```\n\n#### Toggling the Active State on Focus\n\nDrive `active`, and the `expanded` of the items that should open on focus, from a focus/blur handler to animate the tip in and out. Setting `active` slides a bottom tip onto the edge of the input, and removing it (or leaving it unset) collapses it back flush with it; a top tip stays on the border, and only its items expand.\n\n```html\n<div style=\"position: relative;\" id=\"wrapper\">\n <mds-input-tip position=\"top\" id=\"tip\">\n <mds-input-tip-item variant=\"required\"></mds-input-tip-item>\n </mds-input-tip>\n <input\n type=\"text\"\n id=\"field\"\n placeholder=\"Nome utente\"\n />\n</div>\n\n<script>\n const field = document.getElementById('field');\n const tip = document.getElementById('tip');\n const item = tip.querySelector('mds-input-tip-item');\n field.addEventListener('focus', () => { tip.active = true; item.expanded = true; });\n field.addEventListener('blur', () => { tip.active = undefined; item.expanded = undefined; });\n</script>\n```\n\n#### Disabled and Read-only State Chips\n\nWhen the parent input is disabled or read-only, pass the matching `variant` to show a system-translated label. The `expanded` prop on the item keeps it permanently visible even without focus.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"top\">\n <mds-input-tip-item variant=\"disabled\" expanded></mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" disabled placeholder=\"Campo disabilitato\" />\n</div>\n```\n\n#### Required-field Success Feedback\n\nSwitch the `<mds-input-tip-item>` variant to `required-success` once the field passes validation. The item renders a checkmark icon instead of the \"obbligatorio\" label.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"top\" active>\n <mds-input-tip-item variant=\"required-success\" expanded></mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" value=\"Valore valido\" />\n</div>\n```\n\n#### Multiple Tip Items in One Container\n\nSlot several `<mds-input-tip-item>` elements inside a single `<mds-input-tip>`. The container lays them out in a row and hides itself automatically when it has no children.\n\n```html\n<div style=\"position: relative;\">\n <mds-input-tip position=\"bottom\" active>\n <mds-input-tip-item variant=\"text\" expanded>\n Solo lettere e numeri\n </mds-input-tip-item>\n <mds-input-tip-item variant=\"count-almost\" expanded>\n 18 / 20\n </mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" />\n</div>\n```\n\n#### CSS Customization\n\nStyle the tip only through its public `--mds-input-tip-background` CSS custom property; its offsets come from `position` and `active`. Set it on the host or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` ([`agents/color.md`](../../../../agents/color.md)) so dark mode keeps working.\n\n```css\n.custom-input-wrapper mds-input-tip {\n --mds-input-tip-background: rgb(var(--magma-surface-inverse));\n}\n```\n",
|
|
18838
19159
|
"3. Mistakes": "Common incorrect uses of `<mds-input-tip>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use mds-input-tip as a Standalone Tooltip\n\n`<mds-input-tip>` is an internal compound child of [`mds-input`](../mds-input/AGENTS.md), [`mds-input-date`](../mds-input-date/AGENTS.md), and [`mds-input-select`](../mds-input-select/AGENTS.md). It relies on absolute positioning inside a relatively-positioned input shell; outside that context it has no anchor. Use [`mds-tooltip`](../mds-tooltip/AGENTS.md) or [`mds-help`](../mds-help/AGENTS.md) for standalone floating hints.\n\n```html\n<!-- INCORRECT -->\n<mds-input-tip active>\n <mds-input-tip-item variant=\"text\">Suggerimento generico</mds-input-tip-item>\n</mds-input-tip>\n\n<!-- CORRECT -->\n<mds-help>Suggerimento generico</mds-help>\n```\n\n#### Do Not Put Plain Text Directly in the Default Slot\n\nThe default slot of `<mds-input-tip>` accepts only [`mds-input-tip-item`](../mds-input-tip-item/AGENTS.md) elements. Plain text nodes are not styled or accessible. Use `<mds-input-tip-item variant=\"text\">` to carry freeform hint copy.\n\n```html\n<!-- INCORRECT -->\n<mds-input-tip position=\"bottom\" active>\n Inserisci la tua email aziendale\n</mds-input-tip>\n\n<!-- CORRECT -->\n<mds-input-tip position=\"bottom\" active>\n <mds-input-tip-item variant=\"text\">\n Inserisci la tua email aziendale\n </mds-input-tip-item>\n</mds-input-tip>\n```\n\n#### Do Not Set active=\"false\" to Collapse the Tip\n\n`active` is a boolean attribute: remove it (or set the prop to `undefined`) to collapse. A string value is fragile: `\"false\"` is read as `false` on this component, but the attribute stays on the element until the component renders (attribute selectors and scripts reading it see it set). Never write a boolean as a string.\n\n```html\n<!-- INCORRECT -->\n<mds-input-tip position=\"top\" active=\"false\">\n <mds-input-tip-item variant=\"required\"></mds-input-tip-item>\n</mds-input-tip>\n\n<!-- CORRECT -->\n<mds-input-tip position=\"top\">\n <mds-input-tip-item variant=\"required\"></mds-input-tip-item>\n</mds-input-tip>\n```\n\n#### Do Not Use an Undocumented position Value\n\n`position` accepts only `\"top\"` and `\"bottom\"`. Any other value (e.g. `\"left\"`, `\"right\"`) is not typed and has no matching CSS rule; the tip falls back to the initial-value behavior silently.\n\n```html\n<!-- INCORRECT -->\n<mds-input-tip position=\"left\" active>\n <mds-input-tip-item variant=\"text\">Aiuto</mds-input-tip-item>\n</mds-input-tip>\n\n<!-- CORRECT -->\n<mds-input-tip position=\"bottom\" active>\n <mds-input-tip-item variant=\"text\">Aiuto</mds-input-tip-item>\n</mds-input-tip>\n```\n\n#### Do Not Slot Non-tip-item Elements for Custom Styles\n\nSlotting arbitrary HTML or other Magma components (e.g. `<mds-badge>`, `<span>`) bypasses the item's own layout, color tokens, and border-radius joining logic. Always wrap content in `<mds-input-tip-item>`.\n\n```html\n<!-- INCORRECT -->\n<mds-input-tip position=\"bottom\" active>\n <span style=\"color: red;\">Testo personalizzato</span>\n</mds-input-tip>\n\n<!-- CORRECT -->\n<mds-input-tip position=\"bottom\" active>\n <mds-input-tip-item variant=\"text\">Testo personalizzato</mds-input-tip-item>\n</mds-input-tip>\n```\n\n#### Do Not Override Positioning via Inline Styles\n\nThe tip is absolutely positioned by its own CSS, driven by its `position` and `active` props. Setting `position`, `top`, `left`, or `right` inline breaks the animation transform and the active-state offset calculation.\n\n```css\n/* INCORRECT */\nmds-input-tip {\n position: relative;\n top: 10px;\n}\n```\n\n```html\n<!-- CORRECT -->\n<div style=\"position: relative;\">\n <mds-input-tip position=\"bottom\" active>\n <mds-input-tip-item variant=\"text\" expanded>Inserisci almeno 8 caratteri</mds-input-tip-item>\n </mds-input-tip>\n <input type=\"text\" />\n</div>\n```\n"
|
|
18839
19160
|
},
|
|
18840
19161
|
"props": [
|
|
@@ -18849,7 +19170,7 @@
|
|
|
18849
19170
|
"mutable": false,
|
|
18850
19171
|
"attr": "active",
|
|
18851
19172
|
"reflectToAttr": true,
|
|
18852
|
-
"docs": "Moves the tip onto the edge of the input, as the parent input does while it has the
|
|
19173
|
+
"docs": "Moves the bottom tip onto the edge of the input, as the parent input does while it has the\nfocus; the top tip stays on the border of the field. It does not expand the items: each\n`mds-input-tip-item` opens on its own `expanded`",
|
|
18853
19174
|
"docsTags": [
|
|
18854
19175
|
{
|
|
18855
19176
|
"name": "default",
|
|
@@ -18888,7 +19209,7 @@
|
|
|
18888
19209
|
"mutable": false,
|
|
18889
19210
|
"attr": "position",
|
|
18890
19211
|
"reflectToAttr": true,
|
|
18891
|
-
"docs": "Specifies the position of the element relative to its container",
|
|
19212
|
+
"docs": "Specifies the position of the element relative to its container: `top` stands on the top\nborder of the field, half outside, clear of its corner by the radius the field passes down plus\na margin; `bottom` sits inside the bottom edge",
|
|
18892
19213
|
"docsTags": [
|
|
18893
19214
|
{
|
|
18894
19215
|
"name": "default",
|
|
@@ -18922,7 +19243,7 @@
|
|
|
18922
19243
|
{
|
|
18923
19244
|
"name": "--mds-input-tip-active-translate",
|
|
18924
19245
|
"annotation": "prop",
|
|
18925
|
-
"docs": "Transform applied to the tip when active",
|
|
19246
|
+
"docs": "Transform applied to the bottom tip when active",
|
|
18926
19247
|
"visibility": "internal"
|
|
18927
19248
|
},
|
|
18928
19249
|
{
|
|
@@ -18931,22 +19252,28 @@
|
|
|
18931
19252
|
"docs": "Background color of the input tip",
|
|
18932
19253
|
"visibility": "public"
|
|
18933
19254
|
},
|
|
19255
|
+
{
|
|
19256
|
+
"name": "--mds-input-tip-field-radius",
|
|
19257
|
+
"annotation": "prop",
|
|
19258
|
+
"docs": "The corner radius of the field the tip stands on: the top tip keeps clear of the corner by it, plus a margin",
|
|
19259
|
+
"visibility": "internal"
|
|
19260
|
+
},
|
|
18934
19261
|
{
|
|
18935
19262
|
"name": "--mds-input-tip-horizontal-offset",
|
|
18936
19263
|
"annotation": "prop",
|
|
18937
|
-
"docs": "Default horizontal offset of the
|
|
19264
|
+
"docs": "Default horizontal offset of the bottom tip",
|
|
18938
19265
|
"visibility": "internal"
|
|
18939
19266
|
},
|
|
18940
19267
|
{
|
|
18941
19268
|
"name": "--mds-input-tip-horizontal-offset-focused",
|
|
18942
19269
|
"annotation": "prop",
|
|
18943
|
-
"docs": "Horizontal offset
|
|
19270
|
+
"docs": "Horizontal offset of the bottom tip when the input is focused",
|
|
18944
19271
|
"visibility": "internal"
|
|
18945
19272
|
},
|
|
18946
19273
|
{
|
|
18947
19274
|
"name": "--mds-input-tip-vertical-offset",
|
|
18948
19275
|
"annotation": "prop",
|
|
18949
|
-
"docs": "Vertical offset of the
|
|
19276
|
+
"docs": "Vertical offset of the bottom tip",
|
|
18950
19277
|
"visibility": "internal"
|
|
18951
19278
|
}
|
|
18952
19279
|
],
|
|
@@ -21825,8 +22152,8 @@
|
|
|
21825
22152
|
}
|
|
21826
22153
|
],
|
|
21827
22154
|
"usage": {
|
|
21828
|
-
"1. Description": "The `<mds-modal>` web component is the Magma Design System overlay container for dialogs, presenting content in a windowed surface layered above the page with an optional backdrop. It is the system equivalent of the native `<dialog>` element, adding managed open/close animations, body scroll locking, positioning, and a built-in close affordance.\n\n#### Semantic Behavior\n\n- **Open state**: Visibility is driven by the `opened` prop. Setting it `true` runs the intro animation and emits `mdsModalOpen`; clearing it runs the outro animation and emits `mdsModalClose`.\n- **Programmatic close**: Exposes an async `close()` method that dismisses the modal regardless of `interaction`, mirroring the close-button action.\n- **Show/hide events**: `mdsModalShow` fires when the intro finishes (fully visible) and `mdsModalHide` when the outro finishes (fully hidden), the latter being the safe point to detach the modal to reclaim memory.\n- **Backdrop dismissal**: With `interaction=\"relaxed\"` (default) a click on the backdrop or `Esc` closes the modal. The click counts when it is pressed and released on the backdrop once the window has stopped: a text selection dragged out of a field, a drag from the backdrop into the window or a click while the window is still coming in leave the modal open. With `interaction=\"strict\"` both are ignored, and the touch swipe too (below): only the close button or `close()` can dismiss it.\n- **Body scroll lock**: When `overflow=\"auto\"` the component locks body scroll while open and restores it on close.\n- **Touch dismissal**: On touch devices a horizontal swipe past a threshold closes a `relaxed` modal, respecting the swipe direction implied by edge `position` values.\n- **Slot-driven layout**: With no `window` slot, the default slot renders centered content framed by optional `top` (header) and `bottom` (footer) slots, and a close button is rendered automatically, icon-only and named in the page language (the `lang` of `<html>`) (\"Close\"). Slotting a `window` element suppresses the built-in chrome and close button so the consumer supplies the entire surface.\n- **Width of a slotted window**: The `window` element stops at the width of a dialog, `--magma-width-dialog` (the column of a form plus its inset, 580px at 16px: `widths/dialog` of the design language), and shrinks with a narrower screen, its margin around it. A class on the element wins over it, for a bespoke surface.\n- **Close button placement**: The built-in close button sits on the backdrop, in a strip the window always leaves free, so a `strict` modal can be closed whatever its content. `left` and `right` leave it at their side at every width.\n- **Narrow screens**: At a viewport of 480px or less a window that would fill the screen (`center` and the four corners) leaves a strip of backdrop at the top, where the close button shows, as `left` and `right` leave one at their side; `top` and `bottom` stay as tall as their content but never taller than the screen less that strip, which stays on their free side with the close button at its edge (top right for `bottom`, bottom right for `top`).\n- **Wide screens**: Above 480px every window leaves a strip of backdrop at its side, with the close button at its top: `center`, `top` and `bottom` one on each side, the button at the top right; the corners one on the side away from their own, the button there.\n\n#### Properties & Visual Configurations\n\nThis component does not use the shared `variant` / `tone` ladders; its configuration is structural and motion-oriented.\n\n#### Other behavioral props\n\n- **`position`** sets where the window animates from and rests, from `'center'` to edge and corner anchors (`'top'`, `'bottom-left'`, etc.); edge positions also define the valid swipe-to-dismiss direction.\n- **`animation`** selects the motion style of the window: `'slide'` (default), `'3d'`, or `'custom'` (driven entirely by CSS custom properties).\n- **`interaction`** governs how forgiving dismissal is - `'relaxed'` allows backdrop clicks, `'strict'` requires the close button.\n- **`overflow`** chooses whether the component manages body scroll locking (`'auto'`) or leaves it to the consumer (`'manual'`).\n- **`hideBackdrop`** removes the dimmed overlay behind the window (shown by default).\n",
|
|
21829
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-modal>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Modal with Inline Content\n\nThe simplest form: toggle `opened` from JavaScript to show the dialog. The built-in close button and backdrop dismiss the modal automatically with `interaction=\"relaxed\"` (default). React to the `mdsModalClose` event to sync your state.\n\n```html\n<mds-button id=\"btn-apri\">Apri dialogo</mds-button>\n\n<mds-modal id=\"dialogo\">\n <div class=\"p-400\">\n <mds-text>Sei sicuro di voler continuare?</mds-text>\n </div>\n</mds-modal>\n\n<script>\n const btn = document.getElementById('btn-apri');\n const modal = document.getElementById('dialogo');\n btn.addEventListener('click', () => { modal.opened = true; });\n modal.addEventListener('mdsModalClose', () => { modal.opened = undefined; });\n</script>\n```\n\n#### Fixed Header and Footer via `top` / `bottom` Slots\n\nUse the `top` slot for a sticky header and the `bottom` slot for a sticky footer (e.g. action buttons). The default slot renders scrollable body content between them.\n\n```html\n<mds-modal id=\"modifica-utente\" position=\"right\">\n <header slot=\"top\" class=\"p-400 bg-surface-overlay shadow-ring-weak\">\n <mds-text typography=\"h5\">Modifica utente</mds-text>\n </header>\n\n <div class=\"p-400 grid gap-400\">\n <mds-input-field label=\"Nome\">\n <mds-input name=\"nome\"></mds-input>\n </mds-input-field>\n <mds-input-field label=\"Cognome\">\n <mds-input name=\"cognome\"></mds-input>\n </mds-input-field>\n </div>\n\n <footer slot=\"bottom\" class=\"p-400 flex gap-300 justify-end bg-surface-overlay shadow-ring-weak\">\n <mds-button variant=\"dark\" tone=\"outline\" id=\"btn-annulla\">Annulla</mds-button>\n <mds-button variant=\"primary\" tone=\"strong\" id=\"btn-salva\">Salva</mds-button>\n </footer>\n</mds-modal>\n```\n\n#### Edge and Corner Positions\n\n`position` anchors the window to an edge or corner and drives the slide-in direction. Use `right` or `left` for side panels, `bottom` for mobile drawers.\n\n```html\n<!-- Side panel from the right (default in most app shells) -->\n<mds-modal id=\"pannello-laterale\" position=\"right\">\n <div class=\"p-400\">\n <mds-text>Dettagli del documento</mds-text>\n </div>\n</mds-modal>\n\n<!-- Drawer from the bottom (mobile) -->\n<mds-modal id=\"drawer-mobile\" position=\"bottom\">\n <div class=\"p-400\">\n <mds-text>Azioni disponibili</mds-text>\n </div>\n</mds-modal>\n```\n\n#### Strict Interaction Mode\n\nSet `interaction=\"strict\"` when the user must explicitly confirm or cancel before the dialog closes - for example, a form with unsaved changes. Backdrop clicks, `Esc` and touch swipes are ignored; only the close button or the `close()` method can dismiss the modal.\n\n```html\n<mds-modal id=\"conferma-elimina\" interaction=\"strict\">\n <div class=\"p-400 grid gap-400\">\n <mds-text typography=\"h5\">Eliminare il documento?</mds-text>\n <mds-text>Questa operazione non e' reversibile.</mds-text>\n <div class=\"flex gap-300 justify-end\">\n <mds-button variant=\"dark\" tone=\"outline\" id=\"btn-no\">Annulla</mds-button>\n <mds-button variant=\"error\" tone=\"strong\" id=\"btn-si\">Elimina</mds-button>\n </div>\n </div>\n</mds-modal>\n\n<script>\n document.getElementById('btn-no').addEventListener('click', () => {\n document.getElementById('conferma-elimina').close();\n });\n</script>\n```\n\n#### Programmatic Close via `close()` Method\n\nCall the async `close()` method from JavaScript when you need to dismiss the modal from outside its UI - for example, after a successful async operation.\n\n```html\n<mds-modal id=\"salvataggio\">\n <div class=\"p-400\">\n <mds-text>Salvataggio in corso...</mds-text>\n </div>\n</mds-modal>\n\n<script>\n async function salva() {\n const modal = document.getElementById('salvataggio');\n modal.opened = true;\n await salvaRisorsa();\n await modal.close();\n }\n</script>\n```\n\n#### Listening to Animation Events\n\n`mdsModalShow` fires when the intro animation completes (the modal is fully visible). Use it to focus the first interactive element. `mdsModalHide` fires when the outro animation completes; use it to detach the element or reset content.\n\n```html\n<mds-modal id=\"modal-focus\" position=\"right\">\n <div class=\"p-400\">\n <mds-input-field label=\"Cerca\">\n <mds-input id=\"input-ricerca\" name=\"ricerca\"></mds-input>\n </mds-input-field>\n </div>\n</mds-modal>\n\n<script>\n const modal = document.getElementById('modal-focus');\n const input = document.getElementById('input-ricerca');\n\n modal.addEventListener('mdsModalShow', () => {\n input.setFocus();\n });\n modal.addEventListener('mdsModalHide', () => {\n // safe point to detach or reset content\n modal.opened = undefined;\n });\n</script>\n```\n\n#### Custom Animation Styles\n\n`animation` selects the motion style. `'slide'` (default) translates from the entry edge; `'3d'` adds a perspective tilt; `'custom'` delegates entirely to the CSS custom properties `--mds-modal-custom-closed-transform` and `--mds-modal-custom-window-distance`.\n\n```html\n<!-- 3D perspective tilt animation -->\n<mds-modal id=\"modal-3d\" animation=\"3d\" position=\"center\">\n <div class=\"p-400\">\n <mds-text>Animazione 3D</mds-text>\n </div>\n</mds-modal>\n\n<!-- Custom animation driven by CSS vars -->\n<mds-modal id=\"modal-custom\" animation=\"custom\" position=\"center\">\n <div class=\"p-400\">\n <mds-text>Animazione personalizzata</mds-text>\n </div>\n</mds-modal>\n```\n\n#### The Window of a Dialog via the `window` Slot\n\nSlot an element with `slot=\"window\"` to replace the built-in chrome (the window surface and the close button). A dialog slots an [`mds-banner`](../mds-banner/AGENTS.md) `variant=\"light\"` `tone=\"box\"` `dismissible`: its own close button closes the modal. The slotted element gets no `role` of its own: the `<dialog>` the component renders is already the dialog, named by the `aria-label` of the host. The actions follow the rules of a dialog: the secondary one `dark` `outline`, the main one last.\n\nThe window stops at the width of a dialog, the column of a form plus its inset (`--magma-width-dialog`, 580px at 16px, `widths/dialog` of the design language), and shrinks with a narrower screen. Write no width on it: a form keeps in the window the shape it has in the page.\n\n```html\n<mds-modal id=\"modal-banner\" aria-label=\"Azione richiesta\">\n <mds-banner slot=\"window\" variant=\"light\" tone=\"box\" dismissible headline=\"Azione richiesta\">\n <mds-text typography=\"detail\">Conferma la tua identita' per procedere.</mds-text>\n <mds-button slot=\"action\" variant=\"dark\" tone=\"outline\">Annulla</mds-button>\n <mds-button slot=\"action\" variant=\"primary\" tone=\"strong\">Conferma</mds-button>\n </mds-banner>\n</mds-modal>\n```\n\nA bespoke surface, such as a banner as wide as the screen, writes its own width with a class: from the light DOM it wins over the width of a dialog.\n\n```html\n<mds-modal id=\"modal-novita\" aria-label=\"Novita'\">\n <mds-banner slot=\"window\" class=\"max-w-none\" variant=\"light\" tone=\"box\" dismissible headline=\"Novita'\">\n <mds-text typography=\"detail\">Da oggi puoi firmare i documenti dall'app.</mds-text>\n </mds-banner>\n</mds-modal>\n```\n\n#### Disabling the Backdrop\n\nAdd `hide-backdrop` to render the modal without the dimmed overlay - useful for non-blocking side panels that coexist with interactive page content.\n\n```html\n<mds-modal id=\"pannello-info\" position=\"right\" hide-backdrop>\n <div class=\"p-400\">\n <mds-text>Informazioni contestuali</mds-text>\n </div>\n</mds-modal>\n```\n\n```javascript\n// Remove the backdrop from JavaScript (it applies from the next opening)\ndocument.getElementById('pannello-info').hideBackdrop = true;\n```\n\n#### CSS Customization\n\nSize and place the window only through the public `--mds-modal-*` CSS custom properties. Set them on the host element; the window takes its background, radius and shadow from the component. They size the built-in window: a slotted window takes the width of a dialog, or the one its class gives it.\n\n```css\n/* Narrow center modal */\n#modal-card {\n --mds-modal-window-distance: calc(var(--spacing) * 600);\n --mds-modal-window-overflow: hidden;\n --mds-modal-window-max-width: 480px;\n}\n\n/* Full-width drawer */\n#drawer-bottom {\n --mds-modal-window-max-width: 100%;\n --mds-modal-window-min-width: 100%;\n}\n```\n",
|
|
22155
|
+
"1. Description": "The `<mds-modal>` web component is the Magma Design System overlay container for dialogs, presenting content in a windowed surface layered above the page with an optional backdrop. It is the system equivalent of the native `<dialog>` element, adding managed open/close animations, body scroll locking, positioning, and a built-in close affordance.\n\n#### Semantic Behavior\n\n- **Open state**: Visibility is driven by the `opened` prop. Setting it `true` runs the intro animation and emits `mdsModalOpen`; clearing it runs the outro animation and emits `mdsModalClose`.\n- **Programmatic close**: Exposes an async `close()` method that dismisses the modal regardless of `interaction`, mirroring the close-button action.\n- **Show/hide events**: `mdsModalShow` fires when the intro finishes (fully visible) and `mdsModalHide` when the outro finishes (fully hidden), the latter being the safe point to detach the modal to reclaim memory.\n- **Backdrop dismissal**: With `interaction=\"relaxed\"` (default) a click on the backdrop or `Esc` closes the modal. The click counts when it is pressed and released on the backdrop once the window has stopped: a text selection dragged out of a field, a drag from the backdrop into the window or a click while the window is still coming in leave the modal open. With `interaction=\"strict\"` both are ignored, and the touch swipe too (below): only the close button or `close()` can dismiss it.\n- **Body scroll lock**: When `overflow=\"auto\"` the component locks body scroll while open and restores it on close.\n- **Touch dismissal**: On touch devices a horizontal swipe past a threshold closes a `relaxed` modal, respecting the swipe direction implied by edge `position` values.\n- **Slot-driven layout**: With no `window` slot, the default slot renders centered content framed by optional `top` (header) and `bottom` (footer) slots, and a close button is rendered automatically, icon-only and named in the page language (the `lang` of `<html>`) (\"Close\"). Slotting a `window` element suppresses the built-in chrome and close button so the consumer supplies the entire surface.\n- **Title of a banner window**: An `mds-banner` slotted as the `window` draws its `headline` in `h5`, the title of a dialog (`titles/dialog` of the design language), above the `h6` of the parts and the groups of fields the dialog holds; in the page the banner keeps `h6`. The headline is hidden from screen readers: the dialog takes its name from `aria-label` on the host.\n- **Width of a slotted window**: The `window` element stops at the width of a dialog, `--magma-width-dialog` (the column of a form plus its inset, 580px at 16px: `widths/dialog` of the design language), and shrinks with a narrower screen, its margin around it. A class on the element wins over it, for a bespoke surface.\n- **Close button placement**: The built-in close button sits on the backdrop, in a strip the window always leaves free, so a `strict` modal can be closed whatever its content. `left` and `right` leave it at their side at every width.\n- **Narrow screens**: At a viewport of 480px or less a window that would fill the screen (`center` and the four corners) leaves a strip of backdrop at the top, where the close button shows, as `left` and `right` leave one at their side; `top` and `bottom` stay as tall as their content but never taller than the screen less that strip, which stays on their free side with the close button at its edge (top right for `bottom`, bottom right for `top`).\n- **Wide screens**: Above 480px every window leaves a strip of backdrop at its side, with the close button at its top: `center`, `top` and `bottom` one on each side, the button at the top right; the corners one on the side away from their own, the button there.\n\n#### Properties & Visual Configurations\n\nThis component does not use the shared `variant` / `tone` ladders; its configuration is structural and motion-oriented.\n\n#### Other behavioral props\n\n- **`position`** sets where the window animates from and rests, from `'center'` to edge and corner anchors (`'top'`, `'bottom-left'`, etc.); edge positions also define the valid swipe-to-dismiss direction.\n- **`animation`** selects the motion style of the window: `'slide'` (default), `'3d'`, or `'custom'` (driven entirely by CSS custom properties).\n- **`interaction`** governs how forgiving dismissal is - `'relaxed'` allows backdrop clicks, `'strict'` requires the close button.\n- **`overflow`** chooses whether the component manages body scroll locking (`'auto'`) or leaves it to the consumer (`'manual'`).\n- **`hideBackdrop`** removes the dimmed overlay behind the window (shown by default).\n",
|
|
22156
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-modal>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Modal with Inline Content\n\nThe simplest form: toggle `opened` from JavaScript to show the dialog. The built-in close button and backdrop dismiss the modal automatically with `interaction=\"relaxed\"` (default). React to the `mdsModalClose` event to sync your state.\n\n```html\n<mds-button id=\"btn-apri\">Apri dialogo</mds-button>\n\n<mds-modal id=\"dialogo\">\n <div class=\"p-400\">\n <mds-text>Sei sicuro di voler continuare?</mds-text>\n </div>\n</mds-modal>\n\n<script>\n const btn = document.getElementById('btn-apri');\n const modal = document.getElementById('dialogo');\n btn.addEventListener('click', () => { modal.opened = true; });\n modal.addEventListener('mdsModalClose', () => { modal.opened = undefined; });\n</script>\n```\n\n#### Fixed Header and Footer via `top` / `bottom` Slots\n\nUse the `top` slot for a sticky header and the `bottom` slot for a sticky footer (e.g. action buttons). The default slot renders scrollable body content between them.\n\n```html\n<mds-modal id=\"modifica-utente\" position=\"right\">\n <header slot=\"top\" class=\"p-400 bg-surface-overlay shadow-ring-weak\">\n <mds-text typography=\"h5\">Modifica utente</mds-text>\n </header>\n\n <div class=\"p-400 grid gap-400\">\n <mds-input-field label=\"Nome\">\n <mds-input name=\"nome\"></mds-input>\n </mds-input-field>\n <mds-input-field label=\"Cognome\">\n <mds-input name=\"cognome\"></mds-input>\n </mds-input-field>\n </div>\n\n <footer slot=\"bottom\" class=\"p-400 flex gap-300 justify-end bg-surface-overlay shadow-ring-weak\">\n <mds-button variant=\"dark\" tone=\"outline\" id=\"btn-annulla\">Annulla</mds-button>\n <mds-button variant=\"primary\" tone=\"strong\" id=\"btn-salva\">Salva</mds-button>\n </footer>\n</mds-modal>\n```\n\n#### Edge and Corner Positions\n\n`position` anchors the window to an edge or corner and drives the slide-in direction. Use `right` or `left` for side panels, `bottom` for mobile drawers.\n\n```html\n<!-- Side panel from the right (default in most app shells) -->\n<mds-modal id=\"pannello-laterale\" position=\"right\">\n <div class=\"p-400\">\n <mds-text>Dettagli del documento</mds-text>\n </div>\n</mds-modal>\n\n<!-- Drawer from the bottom (mobile) -->\n<mds-modal id=\"drawer-mobile\" position=\"bottom\">\n <div class=\"p-400\">\n <mds-text>Azioni disponibili</mds-text>\n </div>\n</mds-modal>\n```\n\n#### Strict Interaction Mode\n\nSet `interaction=\"strict\"` when the user must explicitly confirm or cancel before the dialog closes - for example, a form with unsaved changes. Backdrop clicks, `Esc` and touch swipes are ignored; only the close button or the `close()` method can dismiss the modal.\n\n```html\n<mds-modal id=\"conferma-elimina\" interaction=\"strict\">\n <div class=\"p-400 grid gap-400\">\n <mds-text typography=\"h5\">Eliminare il documento?</mds-text>\n <mds-text>Questa operazione non e' reversibile.</mds-text>\n <div class=\"flex gap-300 justify-end\">\n <mds-button variant=\"dark\" tone=\"outline\" id=\"btn-no\">Annulla</mds-button>\n <mds-button variant=\"error\" tone=\"strong\" id=\"btn-si\">Elimina</mds-button>\n </div>\n </div>\n</mds-modal>\n\n<script>\n document.getElementById('btn-no').addEventListener('click', () => {\n document.getElementById('conferma-elimina').close();\n });\n</script>\n```\n\n#### Programmatic Close via `close()` Method\n\nCall the async `close()` method from JavaScript when you need to dismiss the modal from outside its UI - for example, after a successful async operation.\n\n```html\n<mds-modal id=\"salvataggio\">\n <div class=\"p-400\">\n <mds-text>Salvataggio in corso...</mds-text>\n </div>\n</mds-modal>\n\n<script>\n async function salva() {\n const modal = document.getElementById('salvataggio');\n modal.opened = true;\n await salvaRisorsa();\n await modal.close();\n }\n</script>\n```\n\n#### Listening to Animation Events\n\n`mdsModalShow` fires when the intro animation completes (the modal is fully visible). Use it to focus the first interactive element. `mdsModalHide` fires when the outro animation completes; use it to detach the element or reset content.\n\n```html\n<mds-modal id=\"modal-focus\" position=\"right\">\n <div class=\"p-400\">\n <mds-input-field label=\"Cerca\">\n <mds-input id=\"input-ricerca\" name=\"ricerca\"></mds-input>\n </mds-input-field>\n </div>\n</mds-modal>\n\n<script>\n const modal = document.getElementById('modal-focus');\n const input = document.getElementById('input-ricerca');\n\n modal.addEventListener('mdsModalShow', () => {\n input.setFocus();\n });\n modal.addEventListener('mdsModalHide', () => {\n // safe point to detach or reset content\n modal.opened = undefined;\n });\n</script>\n```\n\n#### Custom Animation Styles\n\n`animation` selects the motion style. `'slide'` (default) translates from the entry edge; `'3d'` adds a perspective tilt; `'custom'` delegates entirely to the CSS custom properties `--mds-modal-custom-closed-transform` and `--mds-modal-custom-window-distance`.\n\n```html\n<!-- 3D perspective tilt animation -->\n<mds-modal id=\"modal-3d\" animation=\"3d\" position=\"center\">\n <div class=\"p-400\">\n <mds-text>Animazione 3D</mds-text>\n </div>\n</mds-modal>\n\n<!-- Custom animation driven by CSS vars -->\n<mds-modal id=\"modal-custom\" animation=\"custom\" position=\"center\">\n <div class=\"p-400\">\n <mds-text>Animazione personalizzata</mds-text>\n </div>\n</mds-modal>\n```\n\n#### The Window of a Dialog via the `window` Slot\n\nSlot an element with `slot=\"window\"` to replace the built-in chrome (the window surface and the close button). A dialog slots an [`mds-banner`](../mds-banner/AGENTS.md) `variant=\"light\"` `tone=\"box\"` `dismissible`: its own close button closes the modal. The slotted element gets no `role` of its own: the `<dialog>` the component renders is already the dialog, named by the `aria-label` of the host. The actions follow the rules of a dialog: the secondary one `dark` `outline`, the main one last.\n\nThe window stops at the width of a dialog, the column of a form plus its inset (`--magma-width-dialog`, 580px at 16px, `widths/dialog` of the design language), and shrinks with a narrower screen. Write no width on it: a form keeps in the window the shape it has in the page.\n\nThe headline of the banner is the title of the dialog, in `h5` (`titles/dialog`): the banner takes the style from its place, so write no `typography` on it. It is hidden from screen readers, so the `aria-label` of the host carries the same text.\n\n```html\n<mds-modal id=\"modal-banner\" aria-label=\"Azione richiesta\">\n <mds-banner slot=\"window\" variant=\"light\" tone=\"box\" dismissible headline=\"Azione richiesta\">\n <mds-text typography=\"detail\">Conferma la tua identita' per procedere.</mds-text>\n <mds-button slot=\"action\" variant=\"dark\" tone=\"outline\">Annulla</mds-button>\n <mds-button slot=\"action\" variant=\"primary\" tone=\"strong\">Conferma</mds-button>\n </mds-banner>\n</mds-modal>\n```\n\nA bespoke surface, such as a banner as wide as the screen, writes its own width with a class: from the light DOM it wins over the width of a dialog.\n\n```html\n<mds-modal id=\"modal-novita\" aria-label=\"Novita'\">\n <mds-banner slot=\"window\" class=\"max-w-none\" variant=\"light\" tone=\"box\" dismissible headline=\"Novita'\">\n <mds-text typography=\"detail\">Da oggi puoi firmare i documenti dall'app.</mds-text>\n </mds-banner>\n</mds-modal>\n```\n\n#### Disabling the Backdrop\n\nAdd `hide-backdrop` to render the modal without the dimmed overlay - useful for non-blocking side panels that coexist with interactive page content.\n\n```html\n<mds-modal id=\"pannello-info\" position=\"right\" hide-backdrop>\n <div class=\"p-400\">\n <mds-text>Informazioni contestuali</mds-text>\n </div>\n</mds-modal>\n```\n\n```javascript\n// Remove the backdrop from JavaScript (it applies from the next opening)\ndocument.getElementById('pannello-info').hideBackdrop = true;\n```\n\n#### CSS Customization\n\nSize and place the window only through the public `--mds-modal-*` CSS custom properties. Set them on the host element; the window takes its background, radius and shadow from the component. They size the built-in window: a slotted window takes the width of a dialog, or the one its class gives it.\n\n```css\n/* Narrow center modal */\n#modal-card {\n --mds-modal-window-distance: calc(var(--spacing) * 600);\n --mds-modal-window-overflow: hidden;\n --mds-modal-window-max-width: 480px;\n}\n\n/* Full-width drawer */\n#drawer-bottom {\n --mds-modal-window-max-width: 100%;\n --mds-modal-window-min-width: 100%;\n}\n```\n",
|
|
21830
22157
|
"3. Mistakes": "Common incorrect uses of `<mds-modal>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Set `opened=\"false\"` to Close the Modal\n\nA false boolean is an absent attribute ([`agents/conventions.md`](../../../../agents/conventions.md)). The runtime does parse the string `\"false\"` as `false`, so the modal stays closed, but the attribute is still on the element until the first render, so `[opened]` attribute selectors and any code that reads the attribute see it set. Remove the attribute; from JavaScript set the prop to `undefined` (`false` works too: the component turns it into `undefined`).\n\n```html\n<!-- INCORRECT -->\n<mds-modal id=\"dialogo\" opened=\"false\"></mds-modal>\n\n<!-- CORRECT -->\n<mds-modal id=\"dialogo\"></mds-modal>\n```\n\n#### Do Not Put Content in the `window` Slot Without Replacing the Entire Chrome\n\nThe `window` slot completely bypasses the built-in surface, header/footer regions, and close button. Do not use it to add a header element while expecting the default content area and close button to still render - they will not.\n\n```html\n<!-- INCORRECT: only the slotted header renders; default slot and close button are suppressed -->\n<mds-modal id=\"modal\">\n <header slot=\"window\" class=\"p-400\">Titolo</header>\n <div>Contenuto del dialogo</div>\n</mds-modal>\n\n<!-- CORRECT: use slot=\"top\" for a sticky header, default slot for body -->\n<mds-modal id=\"modal\">\n <header slot=\"top\" class=\"p-400 bg-surface-overlay\">Titolo</header>\n <div class=\"p-400\">Contenuto del dialogo</div>\n</mds-modal>\n```\n\n#### Do Not Size the Window of a Dialog by Hand\n\nA slotted window already stops at the width of a dialog, the column of a form plus its inset (`widths/dialog`), and shrinks with the screen. A width written by hand copies a value the theme no longer moves, and a narrower one breaks the form inside: at `max-w-md` (448px) the body of the window is under the `28rem` of `field-group`, so its short fields stack as on a phone.\n\n```html\n<!-- INCORRECT -->\n<mds-modal aria-label=\"Nuovo referente\">\n <mds-banner slot=\"window\" class=\"max-w-md w-full mx-400\" variant=\"light\" tone=\"box\" dismissible headline=\"Nuovo referente\">\n <fieldset class=\"field-group\">...</fieldset>\n </mds-banner>\n</mds-modal>\n\n<!-- CORRECT -->\n<mds-modal aria-label=\"Nuovo referente\">\n <mds-banner slot=\"window\" variant=\"light\" tone=\"box\" dismissible headline=\"Nuovo referente\">\n <fieldset class=\"field-group\">...</fieldset>\n </mds-banner>\n</mds-modal>\n```\n\n#### Do Not Reach Into Shadow Parts to Style the Window\n\nThe only supported customization surface is the public `--mds-modal-*` CSS custom properties and the documented shadow parts (`dialog`, `window`, `action-close`). Targeting internal shadow selectors couples your code to implementation details that will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-modal >>> .window-content {\n padding: 0;\n}\nmds-modal::part(window) > div {\n border: 2px solid red;\n}\n\n/* CORRECT */\nmds-modal {\n --mds-modal-window-distance: calc(var(--spacing) * 400);\n}\n```\n\n#### Do Not Listen for Native `click` on the Backdrop to Close\n\n`mds-modal` emits `mdsModalClose` when it closes (and `mdsModalHide` when the animation finishes). Listening for a raw `click` on the host or backdrop is fragile - the event target varies by browser and shadow DOM boundary, and your handler ignores `interaction=\"strict\"`.\n\n```javascript\n// INCORRECT\ndocument.getElementById('modal').addEventListener('click', (e) => {\n if (e.target === e.currentTarget) modal.opened = undefined;\n});\n\n// CORRECT\ndocument.getElementById('modal').addEventListener('mdsModalClose', () => {\n modal.opened = undefined;\n});\n```\n\n#### Do Not Use `<dialog>` Directly When `<mds-modal>` Is Available\n\nUsing a raw `<dialog>` element bypasses the system's managed animation, body-scroll locking, touch-swipe dismissal, and design-token theming. Always use `<mds-modal>` for overlays in a Magma application.\n\n```html\n<!-- INCORRECT -->\n<dialog id=\"raw-dialog\">\n <p>Contenuto del dialogo</p>\n <button>Chiudi</button>\n</dialog>\n\n<!-- CORRECT -->\n<mds-modal id=\"modal\">\n <div class=\"p-400\">\n <mds-text>Contenuto del dialogo</mds-text>\n </div>\n</mds-modal>\n```\n"
|
|
21831
22158
|
},
|
|
21832
22159
|
"props": [
|
|
@@ -23575,8 +23902,8 @@
|
|
|
23575
23902
|
}
|
|
23576
23903
|
],
|
|
23577
23904
|
"usage": {
|
|
23578
|
-
"1. Description": "The `<mds-pref>` web component is the accessibility-preferences panel of the Magma Design System: a compound parent that groups user-facing settings (animation, consumption, contrast, theme, language) so people can tune readability, motion, and language for their session. It acts as the coordinator for the `mds-pref-*` children slotted inside it.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-mode`, `mds-pref-theme` and/or `mds-pref-language` children in its default slot; it owns no preference UI of its own beyond coordination (it forwards `size`, flags the document and asks for a reload). The lock of a single-mode theme on `mds-pref-mode` needs no parent: the mode control reads it from `<html>`.\n- **Size propagation**: `size` cascades down to every nested `mds-pref-*` child, on load, on every change and to the children added later; without a `size` on the panel each child keeps its own.\n- **Reload notice**: The panel shows an inline caption prompting the user to refresh the page when a preference that cannot apply live (`consumption` or `language`) changes after load. A `controller` panel, which is hidden, shows none.\n- **Document flag**: While at least one `<mds-pref>` is on the page, `<html>` carries `data-magma-pref`, which turns off the styles' fallback to the OS preferences; it is removed only when the last instance leaves the page, so a settings page that unmounts its own panel leaves the app controller in charge. Moving a panel in the DOM (between a sidebar and a menu, or with a client router that keeps it across pages) keeps the flag and the reload notice.\n- **Live language sync**: When a `language` change is emitted, the panel re-resolves its own locale so the reload notice is shown in the newly selected language.\n\n#### Properties & Visual Configurations\n\n`size` is one of the shared tab sizes and is forwarded to children rather than styling the host directly - set it on the parent and it reaches every child.\n\n#### Other behavioral props\n\n- **`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",
|
|
23579
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-pref>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Full Preferences Panel\n\nThe canonical form: slot every `mds-pref-*` control directly inside `<mds-pref>`. No extra wiring is needed: the mode control follows the active theme by itself (a theme of one mode locks it to that mode).\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-theme>\n <mds-pref-theme-item name=\"default\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"cool\"></mds-pref-theme-item>\n </mds-pref-theme>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Partial Panel - Subset of Controls\n\nSlot only the controls your application needs. `<mds-pref>` renders whatever children are present; omitted controls are simply absent.\n\n```html\n<!-- Accessibility-only panel: contrast and animation controls -->\n<mds-pref>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Controlling Size\n\nThe parent's `size` drives all child controls at once, on load and when it changes.\n\n```html\n<!-- Compact panel for a sidebar or popover -->\n<mds-pref size=\"sm\">\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Headless Controller Mode\n\nSet the `controller` boolean attribute when you need the preference engine to apply saved preferences from `localStorage` on page load without rendering any visible UI. The host is hidden via CSS (`display: none`) and still activates all child preference controls.\n\n```html\n<!-- Place in <body>; the panel is invisible but activates stored preferences -->\n<mds-pref controller>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Language Selector with Multiple Languages\n\n`<mds-pref-language>` requires its child `<mds-pref-language-item>` elements to be present; the items are not self-generating. Pass language codes supported by your application.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Reload Notice Handling\n\n`<mds-pref>` shows an inline caption telling the user to refresh the page after a `consumption` or `language` change: nothing to wire. It shows for a change made after the panel loaded, so the stored choices the controls apply on load raise no notice; a `controller` panel is hidden and shows none.\n",
|
|
23905
|
+
"1. Description": "The `<mds-pref>` web component is the accessibility-preferences panel of the Magma Design System: a compound parent that groups user-facing settings (animation, consumption, contrast, theme, language) so people can tune readability, motion, and language for their session. It acts as the coordinator for the `mds-pref-*` children slotted inside it.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-mode`, `mds-pref-theme` and/or `mds-pref-language` children in its default slot; it owns no preference UI of its own beyond coordination (it forwards `size`, flags the document and asks for a reload). The lock of a single-mode theme on `mds-pref-mode` needs no parent: the mode control reads it from `<html>`.\n- **Size propagation**: `size` cascades down to every nested `mds-pref-*` child, on load, on every change and to the children added later; without a `size` on the panel each child keeps its own.\n- **Reload notice**: The panel shows an inline caption prompting the user to refresh the page when a preference that cannot apply live (`consumption` or `language`) changes after load. A `controller` panel, which is hidden, shows none.\n- **Live language**: Magma components follow `<html lang>` at once; the content of the application may not, which is why a change of language asks for a reload. An application that translates its own content as `<html lang>` changes says so with `live-language`, and the panel asks for no reload after a change of language (a change of consumption still asks).\n- **Document flag**: While at least one `<mds-pref>` is on the page, `<html>` carries `data-magma-pref`, which turns off the styles' fallback to the OS preferences; it is removed only when the last instance leaves the page, so a settings page that unmounts its own panel leaves the app controller in charge. Moving a panel in the DOM (between a sidebar and a menu, or with a client router that keeps it across pages) keeps the flag and the reload notice.\n- **Live language sync**: When a `language` change is emitted, the panel re-resolves its own locale so the reload notice is shown in the newly selected language.\n\n#### Properties & Visual Configurations\n\n`size` is one of the shared tab sizes and is forwarded to children rather than styling the host directly - set it on the parent and it reaches every child.\n\n#### Other behavioral props\n\n- **`live-language`** tells the panel the application follows `<html lang>` on its own, so a change of language shows no reload notice.\n- **`controller`** switches the component from a visible on-DOM panel into a headless controller that applies and reacts to preferences without rendering UI; in this mode it drives document-level preference state without a visible panel.\n",
|
|
23906
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-pref>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Full Preferences Panel\n\nThe canonical form: slot every `mds-pref-*` control directly inside `<mds-pref>`. No extra wiring is needed: the mode control follows the active theme by itself (a theme of one mode locks it to that mode).\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-theme>\n <mds-pref-theme-item name=\"default\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"cool\"></mds-pref-theme-item>\n </mds-pref-theme>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Partial Panel - Subset of Controls\n\nSlot only the controls your application needs. `<mds-pref>` renders whatever children are present; omitted controls are simply absent.\n\n```html\n<!-- Accessibility-only panel: contrast and animation controls -->\n<mds-pref>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Controlling Size\n\nThe parent's `size` drives all child controls at once, on load and when it changes.\n\n```html\n<!-- Compact panel for a sidebar or popover -->\n<mds-pref size=\"sm\">\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n</mds-pref>\n```\n\n#### Headless Controller Mode\n\nSet the `controller` boolean attribute when you need the preference engine to apply saved preferences from `localStorage` on page load without rendering any visible UI. The host is hidden via CSS (`display: none`) and still activates all child preference controls.\n\n```html\n<!-- Place in <body>; the panel is invisible but activates stored preferences -->\n<mds-pref controller>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Language Selector with Multiple Languages\n\n`<mds-pref-language>` requires its child `<mds-pref-language-item>` elements to be present; the items are not self-generating. Pass language codes supported by your application.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Reload Notice Handling\n\n`<mds-pref>` shows an inline caption telling the user to refresh the page after a `consumption` or `language` change: nothing to wire. It shows for a change made after the panel loaded, so the stored choices the controls apply on load raise no notice; a `controller` panel is hidden and shows none.\n\n#### An Application That Follows the Language Live\n\nWhen the application translates its own content as `<html lang>` changes (it observes the attribute, or re-renders on `mdsPrefLanguageChange`), add `live-language`: a change of language then needs no reload, and the panel asks for none. A change of consumption still asks.\n\n```html\n<mds-pref live-language>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n",
|
|
23580
23907
|
"3. Mistakes": "Common incorrect uses of `<mds-pref>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Place Non-Pref Children in the Default Slot\n\nThe default slot accepts only `mds-pref-animation`, `mds-pref-consumption`, `mds-pref-contrast`, `mds-pref-language`, `mds-pref-mode` and `mds-pref-theme` children. Other elements are outside the documented content: they render as extra rows of the panel and take part in no coordination.\n\n```html\n<!-- INCORRECT -->\n<mds-pref>\n <div class=\"custom-section\">Tema</div>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Use `mds-pref-*` Children Outside `<mds-pref>`\n\nEach control applies and stores its own preference, but the coordination between the controls of a panel lives in the parent: only the parent forwards `size` changes and sets the `data-magma-pref` flag that turns off the fallback to the OS preferences. Group the controls of a panel in `<mds-pref>`.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-mode></mds-pref-mode>\n<mds-pref-theme>\n <mds-pref-theme-item name=\"default\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"cool\"></mds-pref-theme-item>\n</mds-pref-theme>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-theme>\n <mds-pref-theme-item name=\"default\"></mds-pref-theme-item>\n <mds-pref-theme-item name=\"cool\"></mds-pref-theme-item>\n </mds-pref-theme>\n</mds-pref>\n```\n\n#### Do Not Set `controller=\"false\"` to Turn Off Controller Mode\n\n`controller` is a boolean attribute, and a false boolean is an absent attribute ([`agents/conventions.md`](../../../../agents/conventions.md)). The runtime parses the string `\"false\"` as `false`, so the panel shows, but the attribute is still on the element until the first render, so `[controller]` attribute selectors (the one that hides the panel included) and any code that reads the attribute see it set. Remove the attribute entirely to switch back to visible mode.\n\n```html\n<!-- INCORRECT -->\n<mds-pref controller=\"false\">\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n</mds-pref>\n```\n\n#### Do Not Listen for the Native `change` Event to Detect Preference Changes\n\nThe controls fire no native `change` event. Use the documented `mdsPrefChange` event emitted by each `mds-pref-*` child: it fires once per change, not on page load, and carries only the `preference` name in `detail`, so read the new value from the child.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelector('mds-pref').addEventListener('change', (e) => {\n console.log(e);\n });\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-pref-mode').addEventListener('mdsPrefChange', (e) => {\n console.log(e.detail.preference);\n });\n</script>\n```\n"
|
|
23581
23908
|
},
|
|
23582
23909
|
"props": [
|
|
@@ -23606,6 +23933,32 @@
|
|
|
23606
23933
|
"getter": false,
|
|
23607
23934
|
"setter": false
|
|
23608
23935
|
},
|
|
23936
|
+
{
|
|
23937
|
+
"name": "liveLanguage",
|
|
23938
|
+
"type": "boolean | undefined",
|
|
23939
|
+
"complexType": {
|
|
23940
|
+
"original": "boolean",
|
|
23941
|
+
"resolved": "boolean | undefined",
|
|
23942
|
+
"references": {}
|
|
23943
|
+
},
|
|
23944
|
+
"mutable": false,
|
|
23945
|
+
"attr": "live-language",
|
|
23946
|
+
"reflectToAttr": true,
|
|
23947
|
+
"docs": "Tells the panel that the application follows `<html lang>` on its own, translating its\ncontent as the language changes, so a change of language needs no reload and shows no notice",
|
|
23948
|
+
"docsTags": [],
|
|
23949
|
+
"values": [
|
|
23950
|
+
{
|
|
23951
|
+
"type": "boolean"
|
|
23952
|
+
},
|
|
23953
|
+
{
|
|
23954
|
+
"type": "undefined"
|
|
23955
|
+
}
|
|
23956
|
+
],
|
|
23957
|
+
"optional": true,
|
|
23958
|
+
"required": false,
|
|
23959
|
+
"getter": false,
|
|
23960
|
+
"setter": false
|
|
23961
|
+
},
|
|
23609
23962
|
{
|
|
23610
23963
|
"name": "size",
|
|
23611
23964
|
"type": "\"md\" | \"sm\" | undefined",
|
|
@@ -24144,7 +24497,7 @@
|
|
|
24144
24497
|
}
|
|
24145
24498
|
],
|
|
24146
24499
|
"usage": {
|
|
24147
|
-
"1. Description": "The `<mds-pref-language>` web component is the language-preference control of the Magma Design System, usually slotted inside the [`<mds-pref>`](../mds-pref/AGENTS.md) panel alongside the other preference children. It renders a labelled tab trigger that opens a dropdown of `<mds-pref-language-item>` entries, letting users switch the active document language and persisting that choice.\n\n#### Semantic Behavior\n\n- **Usually inside `<mds-pref>`**: Placed as a direct slot child of `<mds-pref>`, alongside the other `mds-pref-*` controls; it also works on its own, since it applies and stores the language by itself. What it gives up on its own is in its mistakes. In turn it hosts its own `<mds-pref-language-item>` children, supplied via its default slot.\n- **Default slot hosts the items**: The default slot accepts one or more `<mds-pref-language-item>` elements; when the control loads, and whenever its items change, the item whose `code` matches the resolved language is marked selected; an item added after load is picked like the others (a later change of `set` does not move the selection).\n- **Selection orchestration**: Selecting an item clears the others, closes the dropdown, and resolves the new language - the children report up to this component, which centralizes the single-selection state.\n- **Language resolution & persistence**: When `set` is `auto` the active language is resolved in priority order from the persisted value, then the `<html lang>` attribute, then `navigator.language`. The resolved value is persisted and written to `<html lang>` - the single page-wide source of truth for the language. Every localized Magma component (including ones nested in shadow DOM) reacts automatically through a shared reactive store; there is no per-element `lang` override and no imperative refresh method. Applications that manage the language themselves can simply set `<html lang>`: the store observes it.\n- **Events bubbled to the parent**: Emits `mdsPrefLanguageChange` on every item pick, also when the picked language is already active (detail carries the selected `language` code; it fires just before the language is applied), and `mdsPrefChange` (detail `{ preference: 'language' }`), fired only when the resolved language actually changes, from a pick or from a new `set` value (the initial application on load does not emit). The latter is the event `<mds-pref>` listens to for its \"reload required\" notice, since application-level content may still need a reload.\n- **Invalid codes are ignored**: A `set` value that is neither `auto` nor a language tag (a primary subtag of two or three letters, such as `it` or `haw`, optionally followed by others, such as `it-IT`) is ignored with a console warning: the language in place stays, and on load the one `auto` resolves. A stored value that is no language tag is dropped.\n- **Default-language hint**: When the resolved language differs from the built-in default (`en`), a caption noting the default language is rendered.\n\n#### Properties & Visual Configurations\n\n- **`set`**: The desired language as a BCP 47 short tag (e.g. `it`, `en`, `es-ES`); the special value `auto` (default) defers to the persisted/page/system resolution chain described above. Region subtags are sanitized down to the two-letter language. Set an explicit value only to force a starting language regardless of the user's environment. Supported display languages are Italiano, English, Español and ελληνικά.\n- **`size`**: Sizes the nested tab trigger (`sm` / `md`). Inside `<mds-pref>`, the parent's `size` reaches this control on load and when it changes, and overwrites its own: set it on the parent.\n",
|
|
24500
|
+
"1. Description": "The `<mds-pref-language>` web component is the language-preference control of the Magma Design System, usually slotted inside the [`<mds-pref>`](../mds-pref/AGENTS.md) panel alongside the other preference children. It renders a labelled tab trigger that opens a dropdown of `<mds-pref-language-item>` entries, letting users switch the active document language and persisting that choice.\n\n#### Semantic Behavior\n\n- **Usually inside `<mds-pref>`**: Placed as a direct slot child of `<mds-pref>`, alongside the other `mds-pref-*` controls; it also works on its own, since it applies and stores the language by itself. What it gives up on its own is in its mistakes. In turn it hosts its own `<mds-pref-language-item>` children, supplied via its default slot.\n- **Default slot hosts the items**: The default slot accepts one or more `<mds-pref-language-item>` elements; when the control loads, and whenever its items change, the item whose `code` matches the resolved language is marked selected; an item added after load is picked like the others (a later change of `set` does not move the selection).\n- **Selection orchestration**: Selecting an item clears the others, closes the dropdown, and resolves the new language - the children report up to this component, which centralizes the single-selection state.\n- **Language resolution & persistence**: When `set` is `auto` the active language is resolved in priority order from the persisted value, then the `<html lang>` attribute, then `navigator.language`. The resolved value is persisted and written to `<html lang>` - the single page-wide source of truth for the language. Every localized Magma component (including ones nested in shadow DOM) reacts automatically through a shared reactive store; there is no per-element `lang` override and no imperative refresh method. Applications that manage the language themselves can simply set `<html lang>`: the store observes it.\n- **Events bubbled to the parent**: Emits `mdsPrefLanguageChange` on every item pick, also when the picked language is already active (detail carries the selected `language` code; it fires just before the language is applied), and `mdsPrefChange` (detail `{ preference: 'language' }`), fired only when the resolved language actually changes, from a pick or from a new `set` value (the initial application on load does not emit). The latter is the event `<mds-pref>` listens to for its \"reload required\" notice, since application-level content may still need a reload; an application that follows `<html lang>` live sets `live-language` on the panel, which then shows no notice for the language.\n- **Invalid codes are ignored**: A `set` value that is neither `auto` nor a language tag (a primary subtag of two or three letters, such as `it` or `haw`, optionally followed by others, such as `it-IT`) is ignored with a console warning: the language in place stays, and on load the one `auto` resolves. A stored value that is no language tag is dropped.\n- **Default-language hint**: When the resolved language differs from the built-in default (`en`), a caption noting the default language is rendered.\n\n#### Properties & Visual Configurations\n\n- **`set`**: The desired language as a BCP 47 short tag (e.g. `it`, `en`, `es-ES`); the special value `auto` (default) defers to the persisted/page/system resolution chain described above. Region subtags are sanitized down to the two-letter language. Set an explicit value only to force a starting language regardless of the user's environment. Supported display languages are Italiano, English, Español and ελληνικά.\n- **`size`**: Sizes the nested tab trigger (`sm` / `md`). Inside `<mds-pref>`, the parent's `size` reaches this control on load and when it changes, and overwrites its own: set it on the parent.\n",
|
|
24148
24501
|
"2. Examples": "Correct and idiomatic ways to use the `<mds-pref-language>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Language Selector Inside `mds-pref`\n\nThe canonical usage. Nest `<mds-pref-language>` as a direct child of [`<mds-pref>`](../mds-pref/AGENTS.md) and populate its default slot with one [`<mds-pref-language-item>`](../mds-pref-language-item/AGENTS.md) per supported locale. The `code` attribute on each item must be a valid BCP 47 short tag.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Forcing a Starting Language with `set`\n\nPass an explicit BCP 47 tag to `set` to override the automatic resolution chain. Use this when the application dictates an initial language regardless of the user's browser setting or persisted preference.\n\n```html\n<mds-pref>\n <mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Automatic Language Resolution (default)\n\nOmit `set` (or pass `set=\"auto\"`) to let the component resolve the active language in priority order: persisted user choice, then the page `<html lang>` attribute, then `navigator.language`. This is the right choice for most applications.\n\n```html\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Sizing via `size`\n\nUse the `size` prop to size the tab trigger of a standalone control. Inside [`<mds-pref>`](../mds-pref/AGENTS.md), set `size` on the parent: it forwards it to every `mds-pref-*` child, so the group stays consistent.\n\n```html\n<mds-pref size=\"sm\">\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Listening for Language Changes\n\nListen to `mdsPrefLanguageChange` to react when the user picks a language (for example, to reload the page or re-fetch translated content). The event detail carries the selected `language` code string. It fires on every pick, also when the picked language is already the active one.\n\n```html\n<mds-pref>\n <mds-pref-language id=\"lang-selector\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n\n<script>\n document.querySelector('#lang-selector').addEventListener('mdsPrefLanguageChange', (e) => {\n console.log('Nuova lingua selezionata:', e.detail.language);\n // e.g. reload the page to apply the new locale\n window.location.reload();\n });\n</script>\n```\n\n#### Full Preference Panel with Language\n\n`<mds-pref-language>` is one of several preference children accepted by [`<mds-pref>`](../mds-pref/AGENTS.md). Compose it alongside the other controls to offer a complete preferences UI.\n\n```html\n<mds-pref>\n <mds-pref-mode></mds-pref-mode>\n <mds-pref-contrast></mds-pref-contrast>\n <mds-pref-animation></mds-pref-animation>\n <mds-pref-consumption></mds-pref-consumption>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n <mds-pref-language-item code=\"es\"></mds-pref-language-item>\n <mds-pref-language-item code=\"el\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n",
|
|
24149
24502
|
"3. Mistakes": "Common incorrect uses of `<mds-pref-language>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use Outside `mds-pref`\n\n`<mds-pref-language>` is a compound child designed to live inside [`<mds-pref>`](../mds-pref/AGENTS.md). As a standalone widget it still applies and persists the language, but it leaves the preference group: `<mds-pref>` forwards `size` changes to its `mds-pref-*` children and listens to their `mdsPrefChange` for the reload-required notice.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n</mds-pref-language>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Do Not Slot Arbitrary HTML Instead of `mds-pref-language-item`\n\nThe default slot accepts only `<mds-pref-language-item>` elements. Slotting raw `<button>`, `<li>`, or other elements bypasses the selection orchestration and event wiring the parent depends on.\n\n```html\n<!-- INCORRECT -->\n<mds-pref>\n <mds-pref-language>\n <button>Italiano</button>\n <button>English</button>\n </mds-pref-language>\n</mds-pref>\n\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-language>\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Do Not Pass an Unrecognized Language Code to `set`\n\nThe `set` prop must be either `\"auto\"` or a BCP 47 language tag: a primary subtag of two or three letters, the one of the item dictionary (`it`, `en`, `haw`), optionally followed by others (`it-IT`). Any other value - including language names like `\"italiano\"` or malformed strings like `\"en_US\"` - is ignored with a console warning and the language in place stays. Use the shortest primary subtag: `it`, not the ISO 639-2 `ita`, which has no item and no translation.\n\n```html\n<!-- INCORRECT -->\n<mds-pref-language set=\"italiano\">...</mds-pref-language>\n<mds-pref-language set=\"en_US\">...</mds-pref-language>\n\n<!-- CORRECT -->\n<mds-pref-language set=\"it\">...</mds-pref-language>\n<mds-pref-language set=\"en\">...</mds-pref-language>\n<mds-pref-language set=\"es-ES\">...</mds-pref-language>\n```\n\n#### Do Not Set `selected` Manually on `mds-pref-language-item`\n\nThe parent `<mds-pref-language>` manages the `selected` state of each item automatically based on the active language: when it loads, and whenever its items change, it marks only the item whose `code` matches, and on each pick it clears the siblings. A `selected` written in the markup is overwritten on load; one set later from script leaves the visual selection out of step with the active language.\n\n```html\n<!-- INCORRECT -->\n<mds-pref>\n <mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\" selected></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n\n<!-- CORRECT - the parent derives selection from `set` -->\n<mds-pref>\n <mds-pref-language set=\"it\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n\n#### Do Not Listen to `mdsPrefLanguageItemSelect` Instead of `mdsPrefLanguageChange`\n\n`mdsPrefLanguageItemSelect` is the item's own event, emitted by `<mds-pref-language-item>` and consumed by its parent. Application code should listen to `mdsPrefLanguageChange` on `<mds-pref-language>`: one listener for the whole list, fired after the parent has committed the selection (the language is applied right after it, so read it from `e.detail.language`).\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelector('mds-pref-language-item').addEventListener('mdsPrefLanguageItemSelect', (e) => {\n console.log(e.detail.language);\n });\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-pref-language').addEventListener('mdsPrefLanguageChange', (e) => {\n console.log(e.detail.language);\n });\n</script>\n```\n\n#### Do Not Set Size via CSS Instead of the `size` Prop\n\nThe `size` prop is the only supported way to resize the internal tab trigger. Overriding dimensions with inline styles or CSS custom properties not listed in the component's documented surface couples your code to internal implementation details.\n\n```css\n/* INCORRECT */\nmds-pref-language mds-tab-item {\n font-size: 10px;\n}\n```\n\n```html\n<!-- CORRECT -->\n<mds-pref>\n <mds-pref-language size=\"sm\">\n <mds-pref-language-item code=\"it\"></mds-pref-language-item>\n <mds-pref-language-item code=\"en\"></mds-pref-language-item>\n </mds-pref-language>\n</mds-pref>\n```\n"
|
|
24150
24503
|
},
|
|
@@ -29068,7 +29421,7 @@
|
|
|
29068
29421
|
],
|
|
29069
29422
|
"usage": {
|
|
29070
29423
|
"1. Description": "The `<mds-stepper-bar-item>` web component represents a single step inside a [`<mds-stepper-bar>`](../mds-stepper-bar/AGENTS.md) progress indicator, rendering the step's icon, optional ordinal label, descriptive text and status badge. It has no standalone meaning: it is the unit the parent stepper orchestrates to express a sequential, multi-step flow.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-stepper-bar>`; it is not used standalone or mixed with other child types in that slot.\n- **State driven by the parent**: The `done` and `current` props are not set per item by the consumer - the parent's `itemsDone` prop drives `done`/`current` on each child, so an item's visual state is a function of its position relative to the active step.\n- **Index resolution**: The item computes its own ordinal from its position among the parent's children; this index feeds the localized \"step N\" caption rendered when `step` is enabled.\n- **Three-way status badge**: When `badge` is true the item renders a status badge whose variant and localized text reflect the resolved state - `success`/done, `info`/current, or `dark`/queued.\n- **Icon swap on completion**: The displayed icon switches from `icon` to `iconChecked` once the item is done and no longer current.\n- **Going back**: A step that is done (and not current) is a button in the tab order: a click or Enter emits `mdsStepperBarItemDone` with its `{ value }`. It asks, it does not move: the page goes back by setting `itemsDone` on the bar. The current and the following steps are not interactive.\n- **Localization**: Step, badge and status strings are localized (el/en/es/it).\n\n#### Properties & Visual Configurations\n\nMost state props are managed by the parent rather than the consumer. The props worth configuring directly on each item are:\n\n- **`icon` / `iconChecked`**: Set `icon` for the default and current appearance; set `iconChecked` only when the completed step should show a different glyph (it defaults to `icon`).\n- **`step`**: Enable to surface the auto-numbered \"step N\" caption above the label - use it for explicitly ordered flows where the number aids orientation.\n- **`badge`**: Enable to show the queued/current/done status pill; prefer it when status legibility matters more than horizontal compactness.\n- **`value`**: The token the parent collects from the completed items into the `value` of its `mdsStepperBarChange` detail (comma-joined); set it so the parent can aggregate which steps have been completed.\n- **`typography`**: Overrides the label's typography token (defaults to `h6`); lower it for denser bars.\n",
|
|
29071
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-stepper-bar-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Minimal Step Inside a Stepper Bar\n\nPlace `<mds-stepper-bar-item>` elements as direct children of [`<mds-stepper-bar>`](../mds-stepper-bar/AGENTS.md). Each item requires `label` and `icon`. `items-done` on the parent drives the `done` and `current` state of each child automatically.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n icon=\"mi/baseline/person\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/location-on\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Distinct Icon for the Completed State\n\nSet `icon-checked` to a different slug when the done state should show a different glyph - for example a checkmark. When omitted, `icon-checked` defaults to `icon`.\n\n```html\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Showing the Ordinal Caption with `step`\n\nSet the boolean `step` attribute to surface an auto-numbered \"Step N\" caption above the label. Use this for explicitly ordered flows where the ordinal number aids orientation.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Status Badge via `badge`\n\nSet `badge` to show the localized status pill (Completato / In corso / In coda). Prefer this when status legibility matters more than horizontal compactness.\n\n```html\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Carrying a Value for Event Handling\n\nSet `value` on each item: the parent collects the values of the completed items, comma-joined, into the `value` of its `mdsStepperBarChange` detail. Listen to that event on the parent or a common ancestor.\n\n```html\n<mds-stepper-bar id=\"stepper\" items-done=\"1\">\n <mds-stepper-bar-item\n value=\"dati-personali\"\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n value=\"indirizzo\"\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n value=\"pagamento\"\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n\n<script>\n document.getElementById('stepper').addEventListener('mdsStepperBarChange', (e) => {\n console.log('step completati:', e.detail.value, 'step corrente:', e.detail.step);\n });\n</script>\n```\n\n#### Pairing Step Content via the `content` Slot\n\nPlace panel elements with `slot=\"content\"` inside `<mds-stepper-bar>` - one per item in order. The parent shows only the panel matching the current step (it puts the `hidden` attribute on the others, so no style of the page is needed; a `display` the page sets on a panel overrides it).\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/payment\" label=\"Pagamento\"></mds-stepper-bar-item>\n\n <div slot=\"content\">\n <p>Inserisci il tuo nome e cognome.</p>\n </div>\n <div slot=\"content\">\n <p>Inserisci il tuo indirizzo di spedizione.</p>\n </div>\n <div slot=\"content\">\n <p>Scegli il metodo di pagamento.</p>\n </div>\n</mds-stepper-bar>\n```\n\n#### Reducing Label Typography for Dense Bars\n\nLower the `typography` prop (default `h6`) when horizontal space is tight or when the label must blend with smaller surrounding text.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Styling Customization\n\nStyle items only through the public `--mds-stepper-bar-item-*` CSS custom properties: the text colour and the minimum width. The icon and progress colours follow the state the parent sets (queued, current, done) and are not set by the page. Use semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working. Target the `::part(badge)` surface only when a deep visual override of the badge wrapper is required.\n\n```css\n.checkout-flow mds-stepper-bar-item {\n --mds-stepper-bar-item-color: rgb(var(--magma-text-muted));\n --mds-stepper-bar-item-min-width: 160px;\n}\n```\n",
|
|
29424
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-stepper-bar-item>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Minimal Step Inside a Stepper Bar\n\nPlace `<mds-stepper-bar-item>` elements as direct children of [`<mds-stepper-bar>`](../mds-stepper-bar/AGENTS.md). Each item requires `label` and `icon`. `items-done` on the parent drives the `done` and `current` state of each child automatically.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n icon=\"mi/baseline/person\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/location-on\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Distinct Icon for the Completed State\n\nSet `icon-checked` to a different slug when the done state should show a different glyph - for example a checkmark. When omitted, `icon-checked` defaults to `icon`.\n\n```html\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Showing the Ordinal Caption with `step`\n\nSet the boolean `step` attribute to surface an auto-numbered \"Step N\" caption above the label. Use this for explicitly ordered flows where the ordinal number aids orientation.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n step\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Status Badge via `badge`\n\nSet `badge` to show the localized status pill (Completato / In corso / In coda). Prefer this when status legibility matters more than horizontal compactness.\n\n```html\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n badge\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Carrying a Value for Event Handling\n\nSet `value` on each item: the parent collects the values of the completed items, comma-joined, into the `value` of its `mdsStepperBarChange` detail. Listen to that event on the parent or a common ancestor.\n\n```html\n<mds-stepper-bar id=\"stepper\" items-done=\"1\">\n <mds-stepper-bar-item\n value=\"dati-personali\"\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n value=\"indirizzo\"\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n value=\"pagamento\"\n icon=\"mi/baseline/payment\"\n icon-checked=\"mi/baseline/done\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n\n<script>\n document.getElementById('stepper').addEventListener('mdsStepperBarChange', (e) => {\n console.log('step completati:', e.detail.value, 'step corrente:', e.detail.step);\n });\n</script>\n```\n\n#### Pairing Step Content via the `content` Slot\n\nPlace panel elements with `slot=\"content\"` inside `<mds-stepper-bar>` - one per item in order. The parent shows only the panel matching the current step (it puts the `hidden` attribute on the others, so no style of the page is needed; a `display` the page sets on a panel overrides it).\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/payment\" label=\"Pagamento\"></mds-stepper-bar-item>\n\n <div slot=\"content\">\n <p>Inserisci il tuo nome e cognome.</p>\n </div>\n <div slot=\"content\">\n <p>Inserisci il tuo indirizzo di spedizione.</p>\n </div>\n <div slot=\"content\">\n <p>Scegli il metodo di pagamento.</p>\n </div>\n</mds-stepper-bar>\n```\n\n#### Reducing Label Typography for Dense Bars\n\nLower the `typography` prop (default `h6`) when horizontal space is tight or when the label must blend with smaller surrounding text.\n\n```html\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/person\"\n icon-checked=\"mi/baseline/done\"\n label=\"Dati personali\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/location-on\"\n icon-checked=\"mi/baseline/done\"\n label=\"Indirizzo\"\n ></mds-stepper-bar-item>\n <mds-stepper-bar-item\n typography=\"label\"\n icon=\"mi/baseline/payment\"\n label=\"Pagamento\"\n ></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Styling Customization\n\nStyle items only through the public `--mds-stepper-bar-item-*` CSS custom properties: the text colour and the minimum width. The minimum width applies to every item but the last: the last one draws no bar after its icon, so it takes the width of its texts and the bars of the others fill the rest of the row. The icon and progress colours follow the state the parent sets (queued, current, done) and are not set by the page. Use semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working. Target the `::part(badge)` surface only when a deep visual override of the badge wrapper is required.\n\n```css\n.checkout-flow mds-stepper-bar-item {\n --mds-stepper-bar-item-color: rgb(var(--magma-text-muted));\n --mds-stepper-bar-item-min-width: 160px;\n}\n```\n",
|
|
29072
29425
|
"3. Mistakes": "Common incorrect uses of `<mds-stepper-bar-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use Outside `<mds-stepper-bar>`\n\n`<mds-stepper-bar-item>` is a compound child - its state (`done`, `current`, index) is resolved by the parent. Using it standalone leaves `isDone`, `isCurrent` and `index` at their defaults and produces broken visual output.\n\n```html\n<!-- INCORRECT -->\n<mds-stepper-bar-item icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n\n<!-- CORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Do Not Set `done=\"false\"` or `current=\"false\"` as Strings\n\n`done` and `current` are boolean props. Stencil reads `\"false\"` as `false` and, since both are reflected, removes the attribute at the first render, so this happens to work; but the markup says the opposite of what it does, and on a prop that is not reflected the attribute stays in the DOM, where `[attr]` selectors still match it. To turn them off, remove the attribute or let the parent manage state via `items-done`.\n\n```html\n<!-- INCORRECT -->\n<mds-stepper-bar-item done=\"false\" current=\"false\" icon=\"mi/baseline/payment\" label=\"Pagamento\"></mds-stepper-bar-item>\n\n<!-- CORRECT -->\n<mds-stepper-bar-item icon=\"mi/baseline/payment\" label=\"Pagamento\"></mds-stepper-bar-item>\n```\n\n#### Do Not Override State Manually When the Parent Manages It\n\n`done` and `current` are driven by `<mds-stepper-bar>`'s `items-done` prop. Setting them on individual items and also setting `items-done` creates conflicting state that the parent overwrites when it loads and whenever `items-done` changes.\n\n```html\n<!-- INCORRECT -->\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item done current icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n\n<!-- CORRECT -->\n<mds-stepper-bar items-done=\"2\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Do Not Wrap Items in Extra HTML Elements\n\nEach item numbers itself among its own siblings, and the parent's track lays out its direct children: a wrapper `<div>` or `<li>` turns every wrapped item into \"Step 1\" and breaks the track layout and scroll alignment.\n\n```html\n<!-- INCORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <div>\n <mds-stepper-bar-item icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n </div>\n <div>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" label=\"Indirizzo\"></mds-stepper-bar-item>\n </div>\n</mds-stepper-bar>\n\n<!-- CORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" icon-checked=\"mi/baseline/done\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" icon-checked=\"mi/baseline/done\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n\n#### Do Not Use Undocumented `::part()` Targets to Style the Icon or Progress\n\nThe only documented shadow part is `badge`. Targeting internals such as `::part(icon)` or `::part(progress)` couples code to the private Shadow DOM structure and will break on minor releases. The icon and the progress line take their colours from the step state; style the item through its public `--mds-stepper-bar-item-*` CSS custom properties instead.\n\n```css\n/* INCORRECT */\nmds-stepper-bar-item::part(icon) {\n background-color: purple;\n}\nmds-stepper-bar-item::part(progress) {\n height: 6px;\n}\n\n/* CORRECT */\nmds-stepper-bar-item {\n --mds-stepper-bar-item-color: rgb(var(--magma-text-default));\n --mds-stepper-bar-item-min-width: 160px;\n}\n```\n\n#### Do Not Omit `label` or `icon`\n\nBoth are required props. An item without `label` has no accessible or visual description; an item without `icon` leaves the icon area empty and breaks the progress-line layout.\n\n```html\n<!-- INCORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n\n<!-- CORRECT -->\n<mds-stepper-bar items-done=\"1\">\n <mds-stepper-bar-item icon=\"mi/baseline/person\" label=\"Dati personali\"></mds-stepper-bar-item>\n <mds-stepper-bar-item icon=\"mi/baseline/location-on\" label=\"Indirizzo\"></mds-stepper-bar-item>\n</mds-stepper-bar>\n```\n"
|
|
29073
29426
|
},
|
|
29074
29427
|
"props": [
|
|
@@ -29454,7 +29807,7 @@
|
|
|
29454
29807
|
{
|
|
29455
29808
|
"name": "--mds-stepper-bar-item-min-width",
|
|
29456
29809
|
"annotation": "prop",
|
|
29457
|
-
"docs": "Sets the minimum width of the component",
|
|
29810
|
+
"docs": "Sets the minimum width of the component; the last item, which has no bar, takes the width of its texts instead",
|
|
29458
29811
|
"visibility": "public"
|
|
29459
29812
|
},
|
|
29460
29813
|
{
|
|
@@ -29544,7 +29897,7 @@
|
|
|
29544
29897
|
}
|
|
29545
29898
|
],
|
|
29546
29899
|
"usage": {
|
|
29547
|
-
"1. Description": "The `<mds-tab>` web component is the compound container that orchestrates a tabbed navigation in the Magma Design System. It is the parent wrapper around a set of `<mds-tab-item>` triggers and, when the component shows the content itself, their content panels, providing the ARIA `tablist` structure, selection state, scrolling and the animated selection indicator.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects `<mds-tab-item>` elements in the default slot; each panel in the named `content` slot is wired up automatically and paired by document order; a panel past the last item has no tab to open it, so it stays hidden and the component logs a console warning. The panels are optional: without them the component shows the strip alone, and the page shows the content, driven by `mdsTabChange` or by navigation.\n- **Navigation strip**: When every item has `href`, the items are links (announced as such, the selected one as current) and the strip is no longer a `tablist`: the browser follows the links, in a new tab on a modifier or middle click, and the strip keeps the selected item highlighted. A client-side router cancels the click on the item with `preventDefault()` and routes; a modifier click leaves the selection alone.\n- **Selection ownership**: The active tab is whichever `<mds-tab-item>` carries `selected`; the parent flips `selected` across siblings, shows the corresponding content panel and hides the rest.\n- **Change event**: Emits `mdsTabChange` with the selected item's index (`id`) and `value` whenever the active child changes.\n- **Focus restoration**: After a keyboard activation it re-focuses the selected item's button, so the user does not have to re-locate the tab.\n- **Auto-scroll into view**: On selection or child focus, the active tab is scrolled to the center of its strip.\n- **Overflow tracking**: When `overflow` is enabled, left/right inset shadows appear while the tabs overflow their container.\n- **Size propagation**: The parent `size` is pushed down onto every nested `<mds-tab-item>`, so children should not be sized individually.\n\n#### Properties & Visual Configurations\n\n- **`direction`** chooses whether the tab strip is laid out `'horizontal'` (default) or `'vertical'`.\n- **`animation`** governs the transition between active items: `'slide'` (default) renders the moving slider indicator, while `'fade'` cross-fades without the slider. The slider slides only when the selection changes: on load, and when the strip is shown again after being hidden, it is already under the selected tab.\n- **`fill`** makes the tab strip stretch to occupy the full available width rather than hugging its content.\n- **`overflow`** enables the inset-shadow affordance that signals more tabs exist beyond the visible edges; **`scrollbar`** instead exposes the native horizontal scrollbar for accessibility.\n\n#### Other behavioral props\n\n- **`size`** sets the scale (`'sm'` / `'md'`) for the whole group and is forwarded to the child items; it is the only way to size the tabs consistently.\n",
|
|
29900
|
+
"1. Description": "The `<mds-tab>` web component is the compound container that orchestrates a tabbed navigation in the Magma Design System. It is the parent wrapper around a set of `<mds-tab-item>` triggers and, when the component shows the content itself, their content panels, providing the ARIA `tablist` structure, selection state, scrolling and the animated selection indicator.\n\n#### Semantic Behavior\n\n- **Compound parent**: Expects `<mds-tab-item>` elements in the default slot; each panel in the named `content` slot is wired up automatically and paired by document order; a panel past the last item has no tab to open it, so it stays hidden and the component logs a console warning. The panels are optional: without them the component shows the strip alone, and the page shows the content, driven by `mdsTabChange` or by navigation.\n- **Navigation strip**: When every item has `href`, the items are links (announced as such, the selected one as current) and the strip is no longer a `tablist`: the browser follows the links, in a new tab on a modifier or middle click, and the strip keeps the selected item highlighted. A client-side router cancels the click on the item with `preventDefault()` and routes; a modifier click leaves the selection alone.\n- **Selection ownership**: The active tab is whichever `<mds-tab-item>` carries `selected`; the parent flips `selected` across siblings, shows the corresponding content panel and hides the rest.\n- **Change event**: Emits `mdsTabChange` with the selected item's index (`id`) and `value` whenever the active child changes.\n- **Focus restoration**: After a keyboard activation it re-focuses the selected item's button, so the user does not have to re-locate the tab. An item selected from code (`selected` set by the page) leaves the focus where it is.\n- **Auto-scroll into view**: On selection or child focus, the active tab is scrolled to the center of its strip.\n- **Overflow tracking**: When `overflow` is enabled, left/right inset shadows appear while the tabs overflow their container.\n- **Size propagation**: The parent `size` is pushed down onto every nested `<mds-tab-item>`, so children should not be sized individually.\n\n#### Properties & Visual Configurations\n\n- **`direction`** chooses whether the tab strip is laid out `'horizontal'` (default) or `'vertical'`.\n- **`animation`** governs the transition between active items: `'slide'` (default) renders the moving slider indicator, while `'fade'` cross-fades without the slider. The slider slides only when the selection changes: on load, and when the strip is shown again after being hidden, it is already under the selected tab.\n- **`fill`** makes the tab strip stretch to occupy the full available width rather than hugging its content.\n- **`overflow`** enables the inset-shadow affordance that signals more tabs exist beyond the visible edges; **`scrollbar`** instead exposes the native horizontal scrollbar for accessibility.\n\n#### Other behavioral props\n\n- **`size`** sets the scale (`'sm'` / `'md'`) for the whole group and is forwarded to the child items; it is the only way to size the tabs consistently.\n",
|
|
29548
29901
|
"2. Examples": "Correct and idiomatic ways to use the `<mds-tab>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Tab Group with Managed Panels\n\nThe canonical form. Put `<mds-tab-item>` elements in the default slot and one content element per tab in the named `content` slot. Mark the initially-visible tab with `selected`. Panels are wired up by document order - the first `[slot=content]` element is paired with the first `<mds-tab-item>`.\n\n```html\n<mds-tab>\n <mds-tab-item label=\"Panoramica\" selected></mds-tab-item>\n <mds-tab-item label=\"Dettagli\"></mds-tab-item>\n <mds-tab-item label=\"Allegati\"></mds-tab-item>\n\n <div slot=\"content\">\n <mds-text>Contenuto della scheda Panoramica.</mds-text>\n </div>\n <div slot=\"content\">\n <mds-text>Contenuto della scheda Dettagli.</mds-text>\n </div>\n <div slot=\"content\">\n <mds-text>Contenuto della scheda Allegati.</mds-text>\n </div>\n</mds-tab>\n```\n\n#### Listening to Tab Changes\n\nListen to the `mdsTabChange` event to react when the active panel changes. The event detail carries the zero-based `id` (index) and the optional `value` of the newly selected `<mds-tab-item>`.\n\n```html\n<mds-tab id=\"schede-pratica\">\n <mds-tab-item label=\"Anagrafica\" value=\"anagrafica\" selected></mds-tab-item>\n <mds-tab-item label=\"Documenti\" value=\"documenti\"></mds-tab-item>\n <mds-tab-item label=\"Pagamenti\" value=\"pagamenti\"></mds-tab-item>\n</mds-tab>\n\n<script>\n document.querySelector('#schede-pratica').addEventListener('mdsTabChange', (e) => {\n console.log('scheda attiva:', e.detail.id, e.detail.value);\n });\n</script>\n```\n\n#### Tab Items with Icons\n\nPass an icon slug to `<mds-tab-item>` via the `icon` prop. Icon position defaults to `left`; use `icon-position=\"right\"` for forward-navigation tabs.\n\n```html\n<mds-tab>\n <mds-tab-item label=\"Utente\" icon=\"mi/baseline/person\" selected></mds-tab-item>\n <mds-tab-item label=\"Impostazioni\" icon=\"mi/baseline/settings\"></mds-tab-item>\n <mds-tab-item label=\"Notifiche\" icon=\"mi/baseline/notifications\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Profilo utente.</mds-text></div>\n <div slot=\"content\"><mds-text>Impostazioni account.</mds-text></div>\n <div slot=\"content\"><mds-text>Cronologia notifiche.</mds-text></div>\n</mds-tab>\n```\n\n#### Fill the Available Width\n\nSet `fill` when the tab strip should stretch to occupy the full container width instead of hugging its content.\n\n```html\n<mds-tab fill>\n <mds-tab-item label=\"Riepilogo\" selected></mds-tab-item>\n <mds-tab-item label=\"Cronologia\"></mds-tab-item>\n <mds-tab-item label=\"Statistiche\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Riepilogo pratica.</mds-text></div>\n <div slot=\"content\"><mds-text>Registro modifiche.</mds-text></div>\n <div slot=\"content\"><mds-text>Dati statistici.</mds-text></div>\n</mds-tab>\n```\n\n#### Vertical Direction\n\nUse `direction=\"vertical\"` to stack the tab strip on the side. Pair it with `--mds-tab-direction-vertical-columns` to control the column widths of the sidebar and the content area.\n\n```html\n<mds-tab direction=\"vertical\">\n <mds-tab-item label=\"Dati generali\" selected></mds-tab-item>\n <mds-tab-item label=\"Indirizzi\"></mds-tab-item>\n <mds-tab-item label=\"Contatti\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Dati generali.</mds-text></div>\n <div slot=\"content\"><mds-text>Indirizzi registrati.</mds-text></div>\n <div slot=\"content\"><mds-text>Recapiti di contatto.</mds-text></div>\n</mds-tab>\n```\n\n#### Fade Animation\n\nSwitch to `animation=\"fade\"` to highlight the selected tab in place instead of moving the slider indicator. The panels switch without animation in both modes.\n\n```html\n<mds-tab animation=\"fade\">\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n <mds-tab-item label=\"Seconda\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Pannello 1.</mds-text></div>\n <div slot=\"content\"><mds-text>Pannello 2.</mds-text></div>\n</mds-tab>\n```\n\n#### Overflow Shadow for Many Tabs\n\nEnable `overflow` when the tab strip can contain more items than the viewport permits. Left and right inset shadows appear whenever tabs overflow their container, signalling that scrolling is possible.\n\n```html\n<mds-tab overflow>\n <mds-tab-item label=\"Gennaio\" selected></mds-tab-item>\n <mds-tab-item label=\"Febbraio\"></mds-tab-item>\n <mds-tab-item label=\"Marzo\"></mds-tab-item>\n <mds-tab-item label=\"Aprile\"></mds-tab-item>\n <mds-tab-item label=\"Maggio\"></mds-tab-item>\n <mds-tab-item label=\"Giugno\"></mds-tab-item>\n <mds-tab-item label=\"Luglio\"></mds-tab-item>\n <mds-tab-item label=\"Agosto\"></mds-tab-item>\n <mds-tab-item label=\"Settembre\"></mds-tab-item>\n <mds-tab-item label=\"Ottobre\"></mds-tab-item>\n <mds-tab-item label=\"Novembre\"></mds-tab-item>\n <mds-tab-item label=\"Dicembre\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Scrollbar for Accessible Overflow\n\nUse `scrollbar` instead of (or alongside) `overflow` to expose the native horizontal scrollbar. This is the accessible complement for users who navigate via keyboard or who have motor difficulties.\n\n```html\n<mds-tab scrollbar overflow>\n <mds-tab-item label=\"Sezione A\" selected></mds-tab-item>\n <mds-tab-item label=\"Sezione B\"></mds-tab-item>\n <mds-tab-item label=\"Sezione C\"></mds-tab-item>\n <mds-tab-item label=\"Sezione D\"></mds-tab-item>\n <mds-tab-item label=\"Sezione E\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Sizing\n\nSet `size` on the parent to scale all tabs uniformly. Do not set `size` on individual `<mds-tab-item>` elements - the parent propagates the value automatically.\n\n```html\n<!-- Compact strip, e.g. inside a sidebar or dense toolbar -->\n<mds-tab size=\"sm\">\n <mds-tab-item label=\"Vista elenco\" selected></mds-tab-item>\n <mds-tab-item label=\"Vista griglia\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Navigation Links (href on Tab Items)\n\nWhen each tab leads to an anchor, another page or a route, set `href` on every `<mds-tab-item>` and omit the `content` slot: the items render as links, the browser follows them (in a new tab on a modifier or middle click) and the strip keeps the selected item highlighted. The page content is driven by navigation, not by the managed-panels mechanism.\n\n```html\n<mds-tab>\n <mds-tab-item href=\"#sezione-1\" label=\"Introduzione\" selected></mds-tab-item>\n <mds-tab-item href=\"#sezione-2\" label=\"Requisiti\"></mds-tab-item>\n <mds-tab-item href=\"#sezione-3\" label=\"Conclusioni\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Client-Side Routing (href on Tab Items)\n\nIn a single-page app keep `href` on the items and register the router once with `NavigationService`, from `@maggioli-design-system/magma/services`: a plain click on an item is routed on the client and the selection still moves, with no listener per item. A modifier or middle click stays with the browser, which opens the link in a new tab while the strip stays as it is.\n\n```html\n<mds-tab id=\"sezioni\">\n <mds-tab-item href=\"/pratiche\" label=\"Pratiche\" selected></mds-tab-item>\n <mds-tab-item href=\"/documenti\" label=\"Documenti\"></mds-tab-item>\n <mds-tab-item href=\"/pagamenti\" label=\"Pagamenti\"></mds-tab-item>\n</mds-tab>\n\n<script type=\"module\">\n import { NavigationService } from '@maggioli-design-system/magma/services';\n\n NavigationService.setHandler((href) => router.navigate(href));\n</script>\n```\n\nWithout a registered router, cancel the click on the items and route by hand: the component honours `preventDefault()` and still moves the selection. Leave a modifier click alone.\n\n```html\n<script>\n document.querySelectorAll('#sezioni mds-tab-item').forEach((item) => {\n item.addEventListener('click', (event) => {\n if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;\n event.preventDefault();\n router.navigate(item.href);\n });\n });\n</script>\n```\n\n#### Disabled Tab Item\n\nMark an individual tab as unavailable with `disabled`. The parent's selection mechanism skips it; the tab is removed from the tab order automatically.\n\n```html\n<mds-tab>\n <mds-tab-item label=\"Attivo\" selected></mds-tab-item>\n <mds-tab-item label=\"Non disponibile\" disabled></mds-tab-item>\n <mds-tab-item label=\"Altro\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Contenuto disponibile.</mds-text></div>\n <div slot=\"content\"><mds-text>Contenuto non disponibile.</mds-text></div>\n <div slot=\"content\"><mds-text>Altro contenuto.</mds-text></div>\n</mds-tab>\n```\n\n#### Styling Customization\n\nStyle the component only through its public `--mds-tab-*` CSS custom properties: the background, margin and shadow of the tab strip and the columns of the vertical layout. The colours and shadows of the items and the timing of the transitions are not part of them. Set them on the host or a parent selector; use semantic color roles via `rgb(var(--magma-<role>))` so dark mode and high-contrast modes keep working.\n\n```css\n.scheda-primaria mds-tab {\n --mds-tab-tabs-background: rgb(var(--magma-accent-surface));\n --mds-tab-tabs-wrapper-shadow: 0 0 0 calc(var(--spacing) * 50) rgb(var(--magma-accent-border)) inset;\n}\n```\n\nWith `animation=\"fade\"` every item paints its own states (resting, hover and selected). With the slider (`animation=\"slide\"`) the items stay transparent over it, and the slider (`::part(slider)`) paints the selected one.\n",
|
|
29549
29902
|
"3. Mistakes": "Common incorrect uses of `<mds-tab>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Size Individual Tab Items\n\nSetting `size` on a `<mds-tab-item>` directly is overridden by the parent at render time. Use the `size` prop on `<mds-tab>` to size all tabs uniformly.\n\n```html\n<!-- INCORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Elenco\" size=\"sm\" selected></mds-tab-item>\n <mds-tab-item label=\"Griglia\" size=\"sm\"></mds-tab-item>\n</mds-tab>\n\n<!-- CORRECT -->\n<mds-tab size=\"sm\">\n <mds-tab-item label=\"Elenco\" selected></mds-tab-item>\n <mds-tab-item label=\"Griglia\"></mds-tab-item>\n</mds-tab>\n```\n\n#### Do Not Mix Tab Items and Content Panels Out of Order\n\nPanels in `slot=\"content\"` are wired to `<mds-tab-item>` elements by document order. A missing panel leaves its tab with no content, a wrong ordering shows the wrong panel when a tab is selected.\n\n```html\n<!-- INCORRECT: only two content panels for three tab items -->\n<mds-tab>\n <mds-tab-item label=\"A\" selected></mds-tab-item>\n <mds-tab-item label=\"B\"></mds-tab-item>\n <mds-tab-item label=\"C\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Pannello A.</mds-text></div>\n <div slot=\"content\"><mds-text>Pannello B.</mds-text></div>\n</mds-tab>\n\n<!-- CORRECT: one content panel per tab item, same order -->\n<mds-tab>\n <mds-tab-item label=\"A\" selected></mds-tab-item>\n <mds-tab-item label=\"B\"></mds-tab-item>\n <mds-tab-item label=\"C\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Pannello A.</mds-text></div>\n <div slot=\"content\"><mds-text>Pannello B.</mds-text></div>\n <div slot=\"content\"><mds-text>Pannello C.</mds-text></div>\n</mds-tab>\n```\n\n#### Do Not Mix Link Items and Panel Tabs in One Strip\n\nA strip is either a `tablist` of tabs, each controlling a panel, or a navigation of links (`href` on every item): a link inside a tablist is not a child the role allows, and assistive technology announces the strip wrong. Keep the link out of the strip, as an `<mds-button>` next to it.\n\n```html\n<!-- INCORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Dettagli\" selected></mds-tab-item>\n <mds-tab-item label=\"Allegati\"></mds-tab-item>\n <mds-tab-item label=\"Portale\" href=\"https://portale.example.com\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Dettagli.</mds-text></div>\n <div slot=\"content\"><mds-text>Allegati.</mds-text></div>\n <div slot=\"content\"></div>\n</mds-tab>\n\n<!-- CORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Dettagli\" selected></mds-tab-item>\n <mds-tab-item label=\"Allegati\"></mds-tab-item>\n\n <div slot=\"content\"><mds-text>Dettagli.</mds-text></div>\n <div slot=\"content\"><mds-text>Allegati.</mds-text></div>\n</mds-tab>\n<mds-button label=\"Portale\" href=\"https://portale.example.com\" target=\"blank\" tone=\"text\"></mds-button>\n```\n\n#### Do Not Put Tab Items Outside `<mds-tab>`\n\n`<mds-tab-item>` communicates with its parent through internal Stencil events. Used outside `<mds-tab>` it renders as an inert button with no selection, panel, or keyboard management.\n\n```html\n<!-- INCORRECT -->\n<div class=\"my-tab-wrapper\">\n <mds-tab-item label=\"Scheda uno\" selected></mds-tab-item>\n <mds-tab-item label=\"Scheda due\"></mds-tab-item>\n</div>\n<div>...</div>\n\n<!-- CORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Scheda uno\" selected></mds-tab-item>\n <mds-tab-item label=\"Scheda due\"></mds-tab-item>\n <div slot=\"content\">...</div>\n <div slot=\"content\">...</div>\n</mds-tab>\n```\n\n#### Do Not Listen to the `mdsTabItemSelect` Event from Outside\n\n`mdsTabItemSelect` is the item-level event that `<mds-tab-item>` fires to its parent `<mds-tab>`: its `detail` carries the item element (`target`) and `value`, not the position of the tab. To react to the active tab of the group listen to `mdsTabChange` on `<mds-tab>`, whose `detail` has the tab index (`id`) and `value`.\n\n```html\n<!-- INCORRECT -->\n<mds-tab id=\"schede\">\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n <mds-tab-item label=\"Seconda\"></mds-tab-item>\n</mds-tab>\n\n<script>\n document.querySelector('#schede').addEventListener('mdsTabItemSelect', handler);\n</script>\n\n<!-- CORRECT -->\n<mds-tab id=\"schede\">\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n <mds-tab-item label=\"Seconda\"></mds-tab-item>\n</mds-tab>\n\n<script>\n document.querySelector('#schede').addEventListener('mdsTabChange', handler);\n</script>\n```\n\n#### Do Not Use `scrollbar=\"false\"` or `overflow=\"false\"` to Turn Off Boolean Props\n\nStencil reads `\"false\"` as `false` and, since both props are reflected, removes the attribute at the first render, so this happens to work; but the markup says the opposite of what it does, and on a prop that is not reflected the attribute stays in the DOM, where `[attr]` selectors still match it. Remove the attribute entirely to turn a prop off.\n\n```html\n<!-- INCORRECT -->\n<mds-tab scrollbar=\"false\" overflow=\"false\">\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n</mds-tab>\n\n<!-- CORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Prima\" selected></mds-tab-item>\n</mds-tab>\n```\n\n#### Do Not Place Raw HTML Instead of `<mds-tab-item>` in the Default Slot\n\nThe default slot expects `<mds-tab-item>` elements only. Placing a raw `<button>` or `<a>` there bypasses the ARIA `tablist` structure, selection management, and keyboard handling that `<mds-tab>` provides.\n\n```html\n<!-- INCORRECT -->\n<mds-tab>\n <button class=\"tab\">Documenti</button>\n <button class=\"tab\">Messaggi</button>\n <div slot=\"content\">...</div>\n <div slot=\"content\">...</div>\n</mds-tab>\n\n<!-- CORRECT -->\n<mds-tab>\n <mds-tab-item label=\"Documenti\" selected></mds-tab-item>\n <mds-tab-item label=\"Messaggi\"></mds-tab-item>\n <div slot=\"content\">...</div>\n <div slot=\"content\">...</div>\n</mds-tab>\n```\n\n#### Do Not Customize via Undocumented Shadow Parts or Internal Selectors\n\nThe supported customization surface is the public `--mds-tab-*` CSS custom properties and the documented shadow parts (`tabs`, `contents`, `slider`). Targeting other internals via `>>>`, `/deep/`, or undocumented class names couples your code to the shadow DOM implementation and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-tab >>> .tabs-wrapper {\n background: red;\n}\nmds-tab::part(tabs-wrapper) {\n padding: 0;\n}\n\n/* CORRECT */\nmds-tab {\n --mds-tab-tabs-background: rgb(var(--magma-accent-surface));\n}\nmds-tab::part(tabs) {\n outline: 2px solid rgb(var(--magma-accent-border));\n}\n```\n"
|
|
29550
29903
|
},
|
|
@@ -29998,6 +30351,7 @@
|
|
|
29998
30351
|
],
|
|
29999
30352
|
"states": [],
|
|
30000
30353
|
"dependents": [
|
|
30354
|
+
"mds-input-date-range",
|
|
30001
30355
|
"mds-input-upload",
|
|
30002
30356
|
"mds-pref-animation",
|
|
30003
30357
|
"mds-pref-consumption",
|
|
@@ -30008,6 +30362,9 @@
|
|
|
30008
30362
|
],
|
|
30009
30363
|
"dependencies": [],
|
|
30010
30364
|
"dependencyGraph": {
|
|
30365
|
+
"mds-input-date-range": [
|
|
30366
|
+
"mds-tab"
|
|
30367
|
+
],
|
|
30011
30368
|
"mds-input-upload": [
|
|
30012
30369
|
"mds-tab"
|
|
30013
30370
|
],
|
|
@@ -30848,6 +31205,7 @@
|
|
|
30848
31205
|
],
|
|
30849
31206
|
"states": [],
|
|
30850
31207
|
"dependents": [
|
|
31208
|
+
"mds-input-date-range",
|
|
30851
31209
|
"mds-input-upload",
|
|
30852
31210
|
"mds-pref-animation",
|
|
30853
31211
|
"mds-pref-consumption",
|
|
@@ -30868,6 +31226,9 @@
|
|
|
30868
31226
|
"mds-spinner",
|
|
30869
31227
|
"mds-text"
|
|
30870
31228
|
],
|
|
31229
|
+
"mds-input-date-range": [
|
|
31230
|
+
"mds-tab-item"
|
|
31231
|
+
],
|
|
30871
31232
|
"mds-input-upload": [
|
|
30872
31233
|
"mds-tab-item"
|
|
30873
31234
|
],
|
|
@@ -30929,8 +31290,8 @@
|
|
|
30929
31290
|
}
|
|
30930
31291
|
],
|
|
30931
31292
|
"usage": {
|
|
30932
|
-
"1. Description": "The `<mds-table>` web component is the root container of the Magma Design System tabular data system. It wraps a native `<table>` and orchestrates a family of compound children (`mds-table-header`, `mds-table-body`, `mds-table-footer`, `mds-table-row`, `mds-table-cell`), propagating interaction, selection, and overflow state down to them.\n\n#### Semantic Behavior\n\n- **Compound parent**: The default slot must hold `mds-table-header` / `mds-table-body` / `mds-table-footer`; `<mds-table>` pushes its own `interactive` and `selectable` state onto every `mds-table-row` and the header/body. It is not used standalone.\n- **Selection model**: When `selectable` is set, rows expose a checkbox; the component aggregates the selected rows, mirrors the count to the header's tristate control, and flags that a selection exists so it is visible to CSS and consumers.\n- **Selection event**: Emits `mdsTableSelectionChange` (bubbles, composed) carrying `{ rows }`, an array of `{ index, value }` for every selected row. It follows every change of a row's `selected`, from its checkbox or from code, and `selectAll(select?)`; changes made together are announced once. Both are no-ops unless `selectable` is true.\n- **Live children**: Rows added or removed at runtime are re-wired with the table's interactive and selectable state, so dynamically added rows behave consistently.\n- **Action overflow**: When rows carry a `[slot=\"action\"]`, rows flip into an overlaid-action mode once content exceeds the visible width. Rows and actions added after the first load are followed too: the header gains its Actions column and the new rows the overlay.\n- **Localization**: Resolves its display language from the page (`<html lang>`: `el`/`en`/`es`/`it`, otherwise `en`) for the batch-actions label.\n\n#### Properties & Visual Configurations\n\n- **`interactive`** highlights rows on mouseover; choose it for tables whose rows are clickable or navigable, not for purely static read-only data.\n- **`selectable`** turns on per-row checkbox selection and the aggregated header/batch-actions machinery; without it the selection methods and the `batch-action` slot are inert.\n- **`selection`** is a read-back flag that becomes true while at least one row is selected - it is managed internally, not something callers normally set.\n- **`sorting`** says who orders the rows when a sortable `mds-table-header-cell` changes direction. `internal` (default) moves the rows in the DOM; `external` leaves them where they are, so the application listens to `mdsTableHeaderCellSort` and renders the rows in the order asked. Choose `external` whenever the table shows one page of a larger set (with `mds-paginator`) or the order comes from a back end: sorting the DOM would only sort the page on screen.\n\n#### Other behavioral props\n\n- **`batch-action` slot** holds `mds-button` element/s; its bar renders only when `selectable` is on and at least one batch action is slotted, surfacing a live count badge of the current selection.\n",
|
|
30933
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-table>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Read-Only Table\n\nThe minimal structure: `mds-table-header` with one `mds-table-header-cell` per column, `mds-table-body` with `mds-table-row` children each containing `mds-table-cell` elements. All four subparts are required direct children - do not replace them with raw `<thead>`, `<tr>`, or `<td>` elements.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data iscrizione\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">mario.rossi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">12 ottobre 1985</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Luigi Verdi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">luigi.verdi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">3 marzo 1993</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Layout: Fill the Container and Let the Table Scroll\n\n`<mds-table>` scrolls on its own: its rows sit in an inner wrapper with `overflow: auto`, so when the columns are wider than the table, the table scrolls horizontally inside its own border, and the row actions (`slot=\"action\"`) stay pinned to the visible right edge. It needs no `overflow-x-auto` wrapper of yours, but it needs two things from the page:\n\n- **All the width its container offers**: `w-full` on `<mds-table>`. When that container is a flex or grid item (a `main` next to a sidebar, a `1fr` column), also give the item `min-w-0`: a flex or grid item never shrinks below its content by default, so without it the item grows to the full width of the table and the whole page scrolls instead of the table.\n- **Cells on one line**: `text-wrap: nowrap` on the cells (`[&_mds-table-cell]:text-nowrap` on the table). Wrapping cells squeeze the columns into tall rows and the table never scrolls. `mds-text` with `typography` `paragraph`, `detail` or `caption` sets its own `text-wrap: pretty`, which wins over what it inherits from the cell, so target it too (`[&_mds-text]:text-nowrap`). A long free-text column can keep wrapping if it reads better.\n\n```html\n<div class=\"flex\">\n <aside class=\"w-6400 shrink-0\">...</aside>\n <main class=\"min-w-0 flex-1\">\n <mds-table class=\"w-full [&_mds-table-cell]:text-nowrap [&_mds-text]:text-nowrap\">\n <mds-table-header>\n <mds-table-header-cell label=\"Protocollo\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Oggetto\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ufficio\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">2026/0412</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Contratto di fornitura servizi cloud 2026-2028</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Ufficio acquisti e gare</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">12 marzo 2026</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n </mds-table>\n </main>\n</div>\n```\n\nTo scroll vertically as well, bound the table's height: in a fixed-height panel, make the panel a flex column and give the table `flex-1 min-h-0` (or put `h-full` or a `max-h-*` on the table). The header row scrolls with the body, it is not sticky.\n\n```html\n<section class=\"flex h-9600 flex-col\">\n <mds-table class=\"min-h-0 flex-1 [&_mds-table-cell]:text-nowrap [&_mds-text]:text-nowrap\">\n ...\n </mds-table>\n</section>\n```\n\nWithout Tailwind, the same rules in CSS:\n\n```css\n.content {\n min-width: 0;\n}\n\n.content mds-table {\n width: 100%;\n}\n\n.content mds-table-cell,\n.content mds-table-cell mds-text {\n text-wrap: nowrap;\n}\n```\n\n#### Table with Footer\n\nAdd `mds-table-footer` after `mds-table-body` to show totals or summaries. Each cell inside the footer is an `mds-table-cell` - the same component used in body rows.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Voce\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Importo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Servizio A</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">120,00 EUR</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Servizio B</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">80,00 EUR</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-table-footer>\n <mds-table-cell><mds-text typography=\"action\">Totale</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"action\">200,00 EUR</mds-text></mds-table-cell>\n </mds-table-footer>\n</mds-table>\n```\n\n#### Interactive Rows\n\nSet `interactive` when rows are clickable or navigable. The prop propagates to every `mds-table-row` and highlights the hovered row. Do not reach into rows directly to set `interactive` - set it once on the parent.\n\n```html\n<mds-table interactive>\n <mds-table-header>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ruolo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Anna Bianchi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Amministratore</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Carlo Neri</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Operatore</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Row-Level Action Buttons\n\nSlot `mds-button` elements with `slot=\"action\"` directly inside `mds-table-row` (not inside `mds-table-cell`). The table detects the presence of action buttons and switches to overlay-action mode automatically when content overflows the visible width.\n\n```html\n<mds-table interactive>\n <mds-table-header>\n <mds-table-header-cell label=\"Documento\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Contratto 2024.pdf</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Approvato</mds-text></mds-table-cell>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/download\"\n title=\"Scarica documento\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/delete\"\n title=\"Elimina documento\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Row Selection and Selection Event\n\nSet `selectable` to add a checkbox to each row. Listen for `mdsTableSelectionChange` to receive the array of selected rows - each entry carries the row `index` and the optional `value` set on `mds-table-row`. Assign `value` to each row to distinguish selections in the event payload.\n\n```html\n<mds-table selectable id=\"tabella-utenti\">\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Reparto\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"usr-001\">\n <mds-table-cell><mds-text typography=\"detail\">Giulia Russo</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Contabilita</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"usr-002\">\n <mds-table-cell><mds-text typography=\"detail\">Marco Ferrari</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">IT</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n document.getElementById('tabella-utenti').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n // e.detail.rows => [{ index: 0, value: 'usr-001' }, ...]\n });\n</script>\n```\n\n#### Programmatic Select All\n\nCall the `selectAll()` method to select all rows at once; pass `false` to deselect. This is a no-op unless `selectable` is set.\n\n```html\n<mds-button id=\"btn-seleziona-tutti\" label=\"Seleziona tutti\" variant=\"primary\" tone=\"outline\"></mds-button>\n<mds-button id=\"btn-deseleziona\" label=\"Deseleziona tutti\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-table selectable id=\"tabella-doc\">\n <mds-table-header>\n <mds-table-header-cell label=\"Titolo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"doc-1\">\n <mds-table-cell><mds-text typography=\"detail\">Verbale assemblea</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"doc-2\">\n <mds-table-cell><mds-text typography=\"detail\">Bilancio 2024</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n const table = document.getElementById('tabella-doc');\n document.getElementById('btn-seleziona-tutti').addEventListener('click', () => table.selectAll());\n document.getElementById('btn-deseleziona').addEventListener('click', () => table.selectAll(false));\n</script>\n```\n\n#### Batch Actions Bar\n\nSlot `mds-button` elements with `slot=\"batch-action\"` as direct children of `mds-table` alongside the body. The bar renders only when `selectable` is set and at least one batch-action button is present, a button added after load included; it shows a live count badge of the current selection and appears once a row is checked.\n\n```html\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Pratica\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"prat-001\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica n. 1234</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">In lavorazione</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"prat-002\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica n. 5678</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Chiusa</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-button\n slot=\"batch-action\"\n icon=\"mi/outline/send\"\n label=\"Invia selezionati\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n <mds-button\n slot=\"batch-action\"\n icon=\"mi/outline/delete\"\n label=\"Elimina selezionati\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n</mds-table>\n```\n\n#### Sorting by the Back End, with Pages\n\nWhen the table shows one page of a larger set, set `sorting=\"external\"`: a click on a sortable header emits `mdsTableHeaderCellSort` with the column (`index`, and `sortKey` when the cell has `sort-key`) and the `direction`, and moves no row. The application asks the back end for the first page in that order and renders it; the header shows the direction (icon and `aria-sort`). A `direction` set by the application, for example restored from the address, is shown the same way.\n\n```html\n<mds-table id=\"practices\" sorting=\"external\">\n <mds-table-header>\n <mds-table-header-cell label=\"Numero\" sortable sort-key=\"number\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ricevuta il\" sortable sort-key=\"received\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Oggetto\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <!-- the rows of the current page, rendered by the application -->\n </mds-table-body>\n</mds-table>\n<mds-paginator id=\"pages\" pages=\"12\"></mds-paginator>\n```\n\n```js\nconst table = document.querySelector('#practices');\nconst pages = document.querySelector('#pages');\n\ntable.addEventListener('mdsTableHeaderCellSort', async (event) => {\n const { sortKey, direction } = event.detail;\n // direction \"none\" asks for the order of the back end\n await loadPage({ page: 1, sort: direction === 'none' ? undefined : { sortKey, direction } });\n pages.currentPage = 1;\n});\n```\n\n#### Styling Customization\n\nCustomize the table appearance only through its public `--mds-table-*` CSS custom properties: the background, the text colour and the cell padding. Set them on the host element or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and themes keep working.\n\n```css\n.tabella-contratti mds-table {\n --mds-table-background: rgb(var(--magma-surface-raised));\n --mds-table-cell-padding: calc(var(--spacing) * 500);\n --mds-table-color: rgb(var(--magma-text-default));\n}\n```\n\nThe frame of the table and the lines inside it - between the rows, under the header, above the footer and at the edge of the batch actions panel - take the `--magma-border-muted` role, so frame and grid read as one and follow the theme and the colour mode.\n",
|
|
31293
|
+
"1. Description": "The `<mds-table>` web component is the root container of the Magma Design System tabular data system. It wraps a native `<table>` and orchestrates a family of compound children (`mds-table-header`, `mds-table-body`, `mds-table-footer`, `mds-table-row`, `mds-table-cell`), propagating interaction, selection, and overflow state down to them.\n\n#### Semantic Behavior\n\n- **Compound parent**: The default slot must hold `mds-table-header` / `mds-table-body` / `mds-table-footer`; `<mds-table>` pushes its own `interactive` and `selectable` state onto every `mds-table-row` and the header/body. It is not used standalone.\n- **Selection model**: When `selectable` is set, rows expose a checkbox; the component aggregates the selected rows, mirrors the count to the header's tristate control, and flags that a selection exists so it is visible to CSS and consumers.\n- **Selection event**: Emits `mdsTableSelectionChange` (bubbles, composed) carrying `{ rows }`, an array of `{ index, value }` for every selected row. It follows every change of a row's `selected`, from its checkbox or from code, and `selectAll(select?)`; changes made together are announced once. Rows that arrive already `selected` (in the markup on load, or rendered later) are counted but not announced, as a native control fires no `change` for its initial value. Both are no-ops unless `selectable` is true.\n- **Live children**: Rows added or removed at runtime are re-wired with the table's interactive and selectable state and counted in the selection, so dynamically added rows behave consistently.\n- **Action overflow**: When rows carry a `[slot=\"action\"]`, rows flip into an overlaid-action mode once content exceeds the visible width. Rows and actions added after the first load are followed too: the header gains its Actions column and the new rows the overlay.\n- **Localization**: Resolves its display language from the page (`<html lang>`: `el`/`en`/`es`/`it`, otherwise `en`) for the batch-actions label.\n\n#### Properties & Visual Configurations\n\n- **`interactive`** highlights rows on mouseover; choose it for tables whose rows are clickable or navigable, not for purely static read-only data.\n- **`selectable`** turns on per-row checkbox selection and the aggregated header/batch-actions machinery; without it the selection methods and the `batch-action` slot are inert.\n- **`selection`** is a read-back flag that becomes true while at least one row is selected - it is managed internally, not something callers normally set.\n- **`sorting`** says who orders the rows when a sortable `mds-table-header-cell` changes direction. `internal` (default) moves the rows in the DOM; `external` leaves them where they are, so the application listens to `mdsTableHeaderCellSort` and renders the rows in the order asked. Choose `external` whenever the table shows one page of a larger set (with `mds-paginator`) or the order comes from a back end: sorting the DOM would only sort the page on screen.\n\n#### Other behavioral props\n\n- **`batch-action` slot** holds `mds-button` element/s; its bar renders only when `selectable` is on and at least one batch action is slotted, surfacing a live count badge of the current selection.\n",
|
|
31294
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-table>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Read-Only Table\n\nThe minimal structure: `mds-table-header` with one `mds-table-header-cell` per column, `mds-table-body` with `mds-table-row` children each containing `mds-table-cell` elements. All four subparts are required direct children - do not replace them with raw `<thead>`, `<tr>`, or `<td>` elements.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data iscrizione\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">mario.rossi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">12 ottobre 1985</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Luigi Verdi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">luigi.verdi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">3 marzo 1993</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Layout: Fill the Container and Let the Table Scroll\n\n`<mds-table>` scrolls on its own: its rows sit in an inner wrapper with `overflow: auto`, so when the columns are wider than the table, the table scrolls horizontally inside its own border, and the row actions (`slot=\"action\"`) stay pinned to the visible right edge. It needs no `overflow-x-auto` wrapper of yours, but it needs two things from the page:\n\n- **All the width its container offers**: `w-full` on `<mds-table>`. When that container is a flex or grid item (a `main` next to a sidebar, a `1fr` column), also give the item `min-w-0`: a flex or grid item never shrinks below its content by default, so without it the item grows to the full width of the table and the whole page scrolls instead of the table.\n- **Cells on one line**: `text-wrap: nowrap` on the cells (`[&_mds-table-cell]:text-nowrap` on the table). Wrapping cells squeeze the columns into tall rows and the table never scrolls. `mds-text` with `typography` `paragraph`, `detail` or `caption` sets its own `text-wrap: pretty`, which wins over what it inherits from the cell, so target it too (`[&_mds-text]:text-nowrap`). A long free-text column can keep wrapping if it reads better.\n\n```html\n<div class=\"flex\">\n <aside class=\"w-6400 shrink-0\">...</aside>\n <main class=\"min-w-0 flex-1\">\n <mds-table class=\"w-full [&_mds-table-cell]:text-nowrap [&_mds-text]:text-nowrap\">\n <mds-table-header>\n <mds-table-header-cell label=\"Protocollo\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Oggetto\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ufficio\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">2026/0412</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Contratto di fornitura servizi cloud 2026-2028</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Ufficio acquisti e gare</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">12 marzo 2026</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n </mds-table>\n </main>\n</div>\n```\n\nTo scroll vertically as well, bound the table's height: in a fixed-height panel, make the panel a flex column and give the table `flex-1 min-h-0` (or put `h-full` or a `max-h-*` on the table). The header row scrolls with the body, it is not sticky.\n\n```html\n<section class=\"flex h-9600 flex-col\">\n <mds-table class=\"min-h-0 flex-1 [&_mds-table-cell]:text-nowrap [&_mds-text]:text-nowrap\">\n ...\n </mds-table>\n</section>\n```\n\nWithout Tailwind, the same rules in CSS:\n\n```css\n.content {\n min-width: 0;\n}\n\n.content mds-table {\n width: 100%;\n}\n\n.content mds-table-cell,\n.content mds-table-cell mds-text {\n text-wrap: nowrap;\n}\n```\n\n#### Table with Footer\n\nAdd `mds-table-footer` after `mds-table-body` to show totals or summaries. Each cell inside the footer is an `mds-table-cell` - the same component used in body rows.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Voce\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Importo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Servizio A</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">120,00 EUR</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Servizio B</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">80,00 EUR</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-table-footer>\n <mds-table-cell><mds-text typography=\"action\">Totale</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"action\">200,00 EUR</mds-text></mds-table-cell>\n </mds-table-footer>\n</mds-table>\n```\n\n#### Interactive Rows\n\nSet `interactive` when rows are clickable or navigable. The prop propagates to every `mds-table-row` and highlights the hovered row. Do not reach into rows directly to set `interactive` - set it once on the parent.\n\n```html\n<mds-table interactive>\n <mds-table-header>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ruolo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Anna Bianchi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Amministratore</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Carlo Neri</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Operatore</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Row-Level Action Buttons\n\nSlot `mds-button` elements with `slot=\"action\"` directly inside `mds-table-row` (not inside `mds-table-cell`). The table detects the presence of action buttons and switches to overlay-action mode automatically when content overflows the visible width.\n\n```html\n<mds-table interactive>\n <mds-table-header>\n <mds-table-header-cell label=\"Documento\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Contratto 2024.pdf</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Approvato</mds-text></mds-table-cell>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/download\"\n title=\"Scarica documento\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/delete\"\n title=\"Elimina documento\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Row Selection and Selection Event\n\nSet `selectable` to add a checkbox to each row. Listen for `mdsTableSelectionChange` to receive the array of selected rows - each entry carries the row `index` and the optional `value` set on `mds-table-row`. Assign `value` to each row to distinguish selections in the event payload.\n\n```html\n<mds-table selectable id=\"tabella-utenti\">\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Reparto\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"usr-001\">\n <mds-table-cell><mds-text typography=\"detail\">Giulia Russo</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Contabilita</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"usr-002\">\n <mds-table-cell><mds-text typography=\"detail\">Marco Ferrari</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">IT</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n document.getElementById('tabella-utenti').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n // e.detail.rows => [{ index: 0, value: 'usr-001' }, ...]\n });\n</script>\n```\n\n#### Rows Selected on Load\n\nWrite `selected` on the rows that start selected, such as a selection the page restores. The table counts them when it loads, as after a click: the header box turns indeterminate (checked when every row is selected) and the bar of the batch actions shows how many. Rows rendered later already `selected` are counted the same way. `mdsTableSelectionChange` is not emitted for them, as a native control fires no `change` for its initial value: the application wrote them, so it already knows them.\n\n```html\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Pratica\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"2026/0097\" selected>\n <mds-table-cell><mds-text typography=\"detail\">Iscrizione anagrafica</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"2026/0094\">\n <mds-table-cell><mds-text typography=\"detail\">Certificato di residenza</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-button slot=\"batch-action\" variant=\"primary\" tone=\"outline\" size=\"sm\">Archivia</mds-button>\n</mds-table>\n```\n\n#### Programmatic Select All\n\nCall the `selectAll()` method to select all rows at once; pass `false` to deselect. This is a no-op unless `selectable` is set.\n\n```html\n<mds-button id=\"btn-seleziona-tutti\" label=\"Seleziona tutti\" variant=\"primary\" tone=\"outline\"></mds-button>\n<mds-button id=\"btn-deseleziona\" label=\"Deseleziona tutti\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-table selectable id=\"tabella-doc\">\n <mds-table-header>\n <mds-table-header-cell label=\"Titolo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"doc-1\">\n <mds-table-cell><mds-text typography=\"detail\">Verbale assemblea</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"doc-2\">\n <mds-table-cell><mds-text typography=\"detail\">Bilancio 2024</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n const table = document.getElementById('tabella-doc');\n document.getElementById('btn-seleziona-tutti').addEventListener('click', () => table.selectAll());\n document.getElementById('btn-deseleziona').addEventListener('click', () => table.selectAll(false));\n</script>\n```\n\n#### Batch Actions Bar\n\nSlot `mds-button` elements with `slot=\"batch-action\"` as direct children of `mds-table` alongside the body. The bar renders only when `selectable` is set and at least one batch-action button is present, a button added after load included; it shows a live count badge of the current selection and appears once a row is checked.\n\n```html\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Pratica\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"prat-001\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica n. 1234</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">In lavorazione</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"prat-002\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica n. 5678</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Chiusa</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-button\n slot=\"batch-action\"\n icon=\"mi/outline/send\"\n label=\"Invia selezionati\"\n variant=\"dark\"\n tone=\"text\"\n ></mds-button>\n <mds-button\n slot=\"batch-action\"\n icon=\"mi/outline/delete\"\n label=\"Elimina selezionati\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n</mds-table>\n```\n\n#### Sorting by the Back End, with Pages\n\nWhen the table shows one page of a larger set, set `sorting=\"external\"`: a click on a sortable header emits `mdsTableHeaderCellSort` with the column (`index`, and `sortKey` when the cell has `sort-key`) and the `direction`, and moves no row. The application asks the back end for the first page in that order and renders it; the header shows the direction (icon and `aria-sort`). A `direction` set by the application, for example restored from the address, is shown the same way.\n\n```html\n<mds-table id=\"practices\" sorting=\"external\">\n <mds-table-header>\n <mds-table-header-cell label=\"Numero\" sortable sort-key=\"number\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ricevuta il\" sortable sort-key=\"received\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Oggetto\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <!-- the rows of the current page, rendered by the application -->\n </mds-table-body>\n</mds-table>\n<mds-paginator id=\"pages\" pages=\"12\"></mds-paginator>\n```\n\n```js\nconst table = document.querySelector('#practices');\nconst pages = document.querySelector('#pages');\n\ntable.addEventListener('mdsTableHeaderCellSort', async (event) => {\n const { sortKey, direction } = event.detail;\n // direction \"none\" asks for the order of the back end\n await loadPage({ page: 1, sort: direction === 'none' ? undefined : { sortKey, direction } });\n pages.currentPage = 1;\n});\n```\n\n#### Styling Customization\n\nCustomize the table appearance only through its public `--mds-table-*` CSS custom properties: the background, the text colour and the cell padding. Set them on the host element or a parent selector; use the semantic color roles via `rgb(var(--magma-<role>))` so dark mode and themes keep working.\n\n```css\n.tabella-contratti mds-table {\n --mds-table-background: rgb(var(--magma-surface-raised));\n --mds-table-cell-padding: calc(var(--spacing) * 500);\n --mds-table-color: rgb(var(--magma-text-default));\n}\n```\n\nThe frame of the table and the lines inside it - between the rows, under the header, above the footer and at the edge of the batch actions panel - take the `--magma-border-muted` role, so frame and grid read as one and follow the theme and the colour mode.\n",
|
|
30934
31295
|
"3. Mistakes": "Common incorrect uses of `<mds-table>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Replace Compound Subparts with Raw HTML Elements\n\n`<mds-table>` orchestrates its children via internal Stencil mechanisms. Substituting any subpart (`mds-table-header`, `mds-table-body`, `mds-table-row`, `mds-table-cell`) with a raw `<thead>`, `<tbody>`, `<tr>`, or `<td>` breaks propagation of `interactive`, `selectable`, and overflow state.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <thead>\n <tr><th>Nome</th><th>Email</th></tr>\n </thead>\n <tbody>\n <tr><td>Mario Rossi</td><td>mario.rossi@example.com</td></tr>\n </tbody>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">mario.rossi@example.com</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Do Not Slot Batch-Action Buttons Inside the Body\n\nThe `slot=\"batch-action\"` must be a direct child of `<mds-table>`, not nested inside `mds-table-body` or any row. The component looks for `:scope > [slot=\"batch-action\"]` on load and whenever its children change, and the bar will not appear if the slot is misplaced.\n\n```html\n<!-- INCORRECT -->\n<mds-table selectable>\n <mds-table-body>\n <mds-table-row>...</mds-table-row>\n <mds-button slot=\"batch-action\" label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table selectable>\n <mds-table-header>...</mds-table-header>\n <mds-table-body>\n <mds-table-row>...</mds-table-row>\n </mds-table-body>\n <mds-button slot=\"batch-action\" label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-table>\n```\n\n#### Do Not Slot Row Action Buttons Inside `mds-table-cell`\n\nPer-row action buttons use `slot=\"action\"` on a direct child of `mds-table-row`, not wrapped inside an `mds-table-cell`. Placing them in a cell hides them (`mds-table-cell` has no `action` slot, so the button is not rendered) and breaks the overflow-detection logic that switches rows into overlay-action mode.\n\n```html\n<!-- INCORRECT -->\n<mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Contratto.pdf</mds-text></mds-table-cell>\n <mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" title=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-table-cell>\n</mds-table-row>\n\n<!-- CORRECT -->\n<mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Contratto.pdf</mds-text></mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" title=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-table-row>\n```\n\n#### Do Not Enable Batch Actions Without `selectable`\n\nThe batch-action bar only renders when `selectable` is set. Slotting batch-action buttons on a non-selectable table silently produces no bar and no selection count, causing the buttons to never appear.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header>...</mds-table-header>\n <mds-table-body>...</mds-table-body>\n <mds-button slot=\"batch-action\" label=\"Esporta\" variant=\"primary\"></mds-button>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table selectable>\n <mds-table-header>...</mds-table-header>\n <mds-table-body>...</mds-table-body>\n <mds-button slot=\"batch-action\" label=\"Esporta\" variant=\"primary\"></mds-button>\n</mds-table>\n```\n\n#### Do Not Set `interactive` on Individual Rows\n\n`interactive` is a table-level prop that propagates automatically to every `mds-table-row`. Setting it directly on individual rows bypasses the table's state management and leads to inconsistent behavior when rows are added or removed at runtime.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-body>\n <mds-table-row interactive>...</mds-table-row>\n <mds-table-row>...</mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table interactive>\n <mds-table-body>\n <mds-table-row>...</mds-table-row>\n <mds-table-row>...</mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Do Not Listen for Native `change` Events to Track Selection\n\nSelection state is communicated via the `mdsTableSelectionChange` custom event. Native `change` events from the internal checkboxes do not bubble out of the shadow DOM reliably; always use the documented Magma event.\n\n```html\n<!-- INCORRECT -->\n<mds-table selectable id=\"tbl\">...</mds-table>\n<script>\n document.getElementById('tbl').addEventListener('change', (e) => {\n // unreliable - native events do not bubble from shadow DOM\n });\n</script>\n\n<!-- CORRECT -->\n<mds-table selectable id=\"tbl\">...</mds-table>\n<script>\n document.getElementById('tbl').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n });\n</script>\n```\n\n#### Do Not Set `selection` Manually\n\n`selection` is a reflected read-back attribute managed internally by the table. It becomes `true` when at least one row is selected and is intended for CSS attribute selectors or conditional logic in the host app. Setting it from outside does not change which rows are selected and will be overwritten on the next selection update. The table emits `mdsTableSelectionChange` before it updates `selection`, so inside that listener read `e.detail.rows`, not the attribute.\n\n```html\n<!-- INCORRECT -->\n<mds-table selectable selection>\n ...\n</mds-table>\n\n<!-- CORRECT - read it back, do not set it -->\n<mds-table selectable id=\"tbl\">\n ...\n</mds-table>\n<script>\n document.getElementById('tbl').addEventListener('mdsTableSelectionChange', (e) => {\n const hasSelection = e.detail.rows.length > 0;\n document.getElementById('panel-azioni').hidden = !hasSelection;\n });\n</script>\n```\n"
|
|
30935
31296
|
},
|
|
30936
31297
|
"props": [
|
|
@@ -31132,15 +31493,15 @@
|
|
|
31132
31493
|
"location": "global",
|
|
31133
31494
|
"id": "global::Promise"
|
|
31134
31495
|
},
|
|
31135
|
-
"HTMLMdsTableRowElement": {
|
|
31136
|
-
"location": "global",
|
|
31137
|
-
"id": "global::HTMLMdsTableRowElement"
|
|
31138
|
-
},
|
|
31139
31496
|
"MdsTableRowSelection": {
|
|
31140
31497
|
"location": "import",
|
|
31141
31498
|
"path": "./meta/type",
|
|
31142
31499
|
"id": "src/components/mds-table/meta/type.ts::MdsTableRowSelection",
|
|
31143
31500
|
"referenceLocation": "MdsTableRowSelection"
|
|
31501
|
+
},
|
|
31502
|
+
"HTMLMdsTableRowElement": {
|
|
31503
|
+
"location": "global",
|
|
31504
|
+
"id": "global::HTMLMdsTableRowElement"
|
|
31144
31505
|
}
|
|
31145
31506
|
},
|
|
31146
31507
|
"return": "Promise<void>"
|
|
@@ -31170,7 +31531,7 @@
|
|
|
31170
31531
|
},
|
|
31171
31532
|
"cancelable": true,
|
|
31172
31533
|
"composed": true,
|
|
31173
|
-
"docs": "Emits when the selection of a `selectable` table changes, with the index and the value of each\nselected row",
|
|
31534
|
+
"docs": "Emits when the selection of a `selectable` table changes, with the index and the value of each\nselected row. It announces changes only: not the rows that arrive already `selected` (in the\nmarkup on load, or rendered later), which the table counts all the same, as a native control\nfires no `change` for its initial value",
|
|
31174
31535
|
"docsTags": []
|
|
31175
31536
|
}
|
|
31176
31537
|
],
|
|
@@ -31600,9 +31961,9 @@
|
|
|
31600
31961
|
}
|
|
31601
31962
|
],
|
|
31602
31963
|
"usage": {
|
|
31603
|
-
"1. Description": "The `<mds-table-header>` web component is the header region of a Magma table, used exclusively as a direct slot child of its parent [`<mds-table>`](../mds-table/AGENTS.md). It plays the role of an HTML `<thead>`/header row, hosting the column-header cells and, when selection is enabled, the master \"select all\" control.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be slotted directly inside `<mds-table>` alongside `mds-table-body` (and optionally `mds-table-footer`); it is not used standalone. It is itself the header row: its own default slot accepts `mds-table-header-cell` element(s), one per column.\n- **Parent-driven selection state**: When `selectable` is true the header renders a master checkbox that the parent keeps in sync - `indeterminate` for partial selection and `checked` when all rows are selected.\n- **Selection reported upward**: Toggling the master checkbox selects or deselects every row, after which the table re-emits its own `mdsTableSelectionChange` event.\n- **Automatic actions column**: When any row exposes a `[slot=\"action\"]`, the header appends an extra header cell (exposed as the `actions` shadow part) labelled with the localized \"actions\" string.\n- **Localized labels**: The select-all/select-none switch title and the actions label are localized (el/en/es/it).\n\n#### Properties & Visual Configurations\n\nThis child is configured almost entirely by its parent rather than by author-set attributes.\n\n- **`selectable`**: Toggles rendering of the leading master-checkbox column. It is not normally set by hand - `<mds-table>` propagates its own `selectable` prop down to the header, so enabling selection on the table is what surfaces this control here.\n\nBeyond `selectable`, content is provided through the default slot (`mds-table-header-cell` elements); there are no shared `variant`/`tone` ladders on this component.\n",
|
|
31964
|
+
"1. Description": "The `<mds-table-header>` web component is the header region of a Magma table, used exclusively as a direct slot child of its parent [`<mds-table>`](../mds-table/AGENTS.md). It plays the role of an HTML `<thead>`/header row, hosting the column-header cells and, when selection is enabled, the master \"select all\" control.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be slotted directly inside `<mds-table>` alongside `mds-table-body` (and optionally `mds-table-footer`); it is not used standalone. It is itself the header row: its own default slot accepts `mds-table-header-cell` element(s), one per column.\n- **Parent-driven selection state**: When `selectable` is true the header renders a master checkbox that the parent keeps in sync - `indeterminate` for partial selection and `checked` when all rows are selected, rows selected in the markup on load included.\n- **Selection reported upward**: Toggling the master checkbox selects or deselects every row, after which the table re-emits its own `mdsTableSelectionChange` event.\n- **Automatic actions column**: When any row exposes a `[slot=\"action\"]`, the header appends an extra header cell (exposed as the `actions` shadow part) labelled with the localized \"actions\" string.\n- **Localized labels**: The select-all/select-none switch title and the actions label are localized (el/en/es/it). The title says what a click on the switch does: select every row, or deselect them once every row is selected, however they got selected.\n\n#### Properties & Visual Configurations\n\nThis child is configured almost entirely by its parent rather than by author-set attributes.\n\n- **`selectable`**: Toggles rendering of the leading master-checkbox column. It is not normally set by hand - `<mds-table>` propagates its own `selectable` prop down to the header, so enabling selection on the table is what surfaces this control here.\n\nBeyond `selectable`, content is provided through the default slot (`mds-table-header-cell` elements); there are no shared `variant`/`tone` ladders on this component.\n",
|
|
31604
31965
|
"2. Examples": "Correct and idiomatic ways to use the `<mds-table-header>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Column Headers\n\nPlace `<mds-table-header>` as a direct child of `<mds-table>` and fill its default slot with one `<mds-table-header-cell>` per column. Use the `label` prop on each cell - it is the only text source the cell needs.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data registrazione\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <!-- mds-table-row elements -->\n </mds-table-body>\n</mds-table>\n```\n\n#### Sortable Columns\n\nAdd the `sortable` attribute on the `<mds-table-header-cell>` elements whose column should be sortable. The cell cycles through `none`, `ascending`, and `descending` on each click and re-orders the corresponding body rows automatically.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell sortable label=\"Cognome\"></mds-table-header-cell>\n <mds-table-header-cell sortable label=\"Data\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Note\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <!-- mds-table-row elements -->\n </mds-table-body>\n</mds-table>\n```\n\n#### Selectable Table with Master Checkbox\n\nEnable row selection by adding `selectable` on `<mds-table>`. The table propagates the prop down to `<mds-table-header>`, which automatically renders the master \"select all\" checkbox as the first column. Never set `selectable` directly on `<mds-table-header>` - drive it from the table.\n\n```html\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Ruolo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"1\">\n <mds-table-cell>Mario Rossi</mds-table-cell>\n <mds-table-cell>Amministratore</mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"2\">\n <mds-table-cell>Giulia Bianchi</mds-table-cell>\n <mds-table-cell>Editor</mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Reacting to Selection Changes\n\nListen for `mdsTableSelectionChange` on `<mds-table>` to receive the array of selected rows whenever the master checkbox or any individual row checkbox changes.\n\n```html\n<mds-table selectable id=\"tabella-utenti\">\n <mds-table-header>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Stato\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"alice\">\n <mds-table-cell>Alice Verdi</mds-table-cell>\n <mds-table-cell>Attivo</mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"bob\">\n <mds-table-cell>Bob Neri</mds-table-cell>\n <mds-table-cell>Sospeso</mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n document.getElementById('tabella-utenti').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n });\n</script>\n```\n\n#### Actions Column - Automatic Header Cell\n\nWhen any `<mds-table-row>` exposes a `[slot=\"action\"]`, `<mds-table-header>` automatically appends a right-aligned, localized header cell (\"Action\", \"Azione\" in Italian). No extra markup is required in the header - just place your action buttons in the row slots. The column follows the rows at any time, not only on load: a table mounted empty and filled after a fetch gets it when the first row with actions arrives, and loses it when the last one goes (`<mds-table>` tells the header).\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Documento\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Dimensione\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Relazione annuale.pdf</mds-table-cell>\n <mds-table-cell>2,4 MB</mds-table-cell>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/download\"\n title=\"Scarica\"\n variant=\"primary\"\n tone=\"text\"\n ></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Batch Actions with Selection\n\nWhen `selectable` is set and the table has a `batch-action` slot, a batch-actions toolbar slides in whenever rows are selected. The toolbar is owned by `<mds-table>`: every selection change, from a row checkbox or from the master checkbox in `<mds-table-header>`, updates its count and visibility.\n\n```html\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome file\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Tipo\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row value=\"doc1\">\n <mds-table-cell>contratto.pdf</mds-table-cell>\n <mds-table-cell>PDF</mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"doc2\">\n <mds-table-cell>allegato.docx</mds-table-cell>\n <mds-table-cell>Word</mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n <mds-button slot=\"batch-action\" label=\"Elimina selezionati\" variant=\"error\" tone=\"text\"></mds-button>\n <mds-button slot=\"batch-action\" label=\"Esporta\" variant=\"primary\" tone=\"outline\"></mds-button>\n</mds-table>\n```\n\n#### Styling the Actions Part\n\nThe auto-generated actions header cell is exposed as the `actions` shadow part. Target it with `::part(actions)` to adjust alignment or other visual properties.\n\n```css\nmds-table-header::part(actions) {\n text-align: center;\n min-width: 8rem;\n}\n```\n",
|
|
31605
|
-
"3. Mistakes": "Common incorrect uses of `<mds-table-header>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-table-header>` Outside `<mds-table>`\n\n`<mds-table-header>` calls `this.host.closest('mds-table')` during load to wire up selection and action-column detection. Used standalone or inside a raw `<table>` it finds no table: the actions column is never detected, the master checkbox selects nothing, and every selection and sorting feature breaks.\n\n```html\n<!-- INCORRECT -->\n<table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n </mds-table-header>\n</table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n\n#### Do Not Slot `<mds-table-row>` Inside `<mds-table-header>`\n\nThe default slot of `<mds-table-header>` expects `<mds-table-header-cell>` elements - one per column. Slotting `<mds-table-row>` (a body-row component) into the header produces broken layout and wrong ARIA roles.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-row>\n <mds-table-cell>Cognome</mds-table-cell>\n <mds-table-cell>Email</mds-table-cell>\n </mds-table-row>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Cognome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n\n#### Do Not Set `selectable` Directly on `<mds-table-header>`\n\n`selectable` on the header is an internal prop driven by `<mds-table>` - when the table loads and whenever its `selectable` changes, it pushes its own value down. Setting it by hand on the header bypasses that synchronisation path and can leave rows and the master checkbox out of sync.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header selectable>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n\n#### Do Not Add a Manual \"Actions\" Header Cell\n\nThe component detects `[slot=\"action\"]` children in the table body and appends the localized \"Azione\" header cell automatically. Adding your own header cell for actions doubles the column and misaligns the grid.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Azioni\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Mario Rossi</mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" title=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Mario Rossi</mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" title=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Do Not Call `setSelection` from Application Code\n\n`setSelection(selectedItems, totalItems)` is an internal method called by `<mds-table>` after each row selection change. Calling it from application code duplicates the table's internal bookkeeping and can leave the checkbox in an inconsistent state. React to selection results via the `mdsTableSelectionChange` event instead.\n\n```html\n<!-- INCORRECT -->\n<script>\n const header = document.querySelector('mds-table-header');\n header.setSelection(2, 5); // do not call this from app code\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-table').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Selezione corrente:', e.detail.rows);\n });\n</script>\n```\n\n#### Do Not Use Raw `<thead>` / `<th>` Instead of the Component\n\nMixing raw HTML table elements with the Magma compound disrupts the selection wiring, the automatic actions column, and the localized labels that `<mds-table-header>` provides.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <thead>\n <tr>\n <th>Nome</th>\n <th>Email</th>\n </tr>\n </thead>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n"
|
|
31966
|
+
"3. Mistakes": "Common incorrect uses of `<mds-table-header>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-table-header>` Outside `<mds-table>`\n\n`<mds-table-header>` calls `this.host.closest('mds-table')` during load to wire up selection and action-column detection. Used standalone or inside a raw `<table>` it finds no table: the actions column is never detected, the master checkbox selects nothing, and every selection and sorting feature breaks.\n\n```html\n<!-- INCORRECT -->\n<table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n </mds-table-header>\n</table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n\n#### Do Not Slot `<mds-table-row>` Inside `<mds-table-header>`\n\nThe default slot of `<mds-table-header>` expects `<mds-table-header-cell>` elements - one per column. Slotting `<mds-table-row>` (a body-row component) into the header produces broken layout and wrong ARIA roles.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-row>\n <mds-table-cell>Cognome</mds-table-cell>\n <mds-table-cell>Email</mds-table-cell>\n </mds-table-row>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Cognome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n\n#### Do Not Set `selectable` Directly on `<mds-table-header>`\n\n`selectable` on the header is an internal prop driven by `<mds-table>` - when the table loads and whenever its `selectable` changes, it pushes its own value down. Setting it by hand on the header bypasses that synchronisation path and can leave rows and the master checkbox out of sync.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header selectable>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table selectable>\n <mds-table-header>\n <mds-table-header-cell label=\"Utente\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n\n#### Do Not Add a Manual \"Actions\" Header Cell\n\nThe component detects `[slot=\"action\"]` children in the table body and appends the localized \"Azione\" header cell automatically. Adding your own header cell for actions doubles the column and misaligns the grid.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Azioni\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Mario Rossi</mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" title=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell>Mario Rossi</mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" title=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Do Not Call `setSelection` from Application Code\n\n`setSelection(selectedItems, totalItems)` is an internal method called by `<mds-table>` every time it counts the selected rows: on load, after each row selection change and when rows come and go. Calling it from application code duplicates the table's internal bookkeeping and can leave the checkbox in an inconsistent state. React to selection results via the `mdsTableSelectionChange` event instead.\n\n```html\n<!-- INCORRECT -->\n<script>\n const header = document.querySelector('mds-table-header');\n header.setSelection(2, 5); // do not call this from app code\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-table').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Selezione corrente:', e.detail.rows);\n });\n</script>\n```\n\n#### Do Not Use Raw `<thead>` / `<th>` Instead of the Component\n\nMixing raw HTML table elements with the Magma compound disrupts the selection wiring, the automatic actions column, and the localized labels that `<mds-table-header>` provides.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <thead>\n <tr>\n <th>Nome</th>\n <th>Email</th>\n </tr>\n </thead>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body><!-- rows --></mds-table-body>\n</mds-table>\n```\n"
|
|
31606
31967
|
},
|
|
31607
31968
|
"props": [
|
|
31608
31969
|
{
|
|
@@ -31696,10 +32057,6 @@
|
|
|
31696
32057
|
"Promise": {
|
|
31697
32058
|
"location": "global",
|
|
31698
32059
|
"id": "global::Promise"
|
|
31699
|
-
},
|
|
31700
|
-
"HTMLMdsInputSwitchElement": {
|
|
31701
|
-
"location": "global",
|
|
31702
|
-
"id": "global::HTMLMdsInputSwitchElement"
|
|
31703
32060
|
}
|
|
31704
32061
|
},
|
|
31705
32062
|
"return": "Promise<void>"
|
|
@@ -32011,7 +32368,7 @@
|
|
|
32011
32368
|
}
|
|
32012
32369
|
],
|
|
32013
32370
|
"usage": {
|
|
32014
|
-
"1. Description": "The `<mds-table-row>` web component represents a single data row inside a [`<mds-table>`](../mds-table/AGENTS.md) (slotted through `mds-table-body`; `mds-table-header` and `mds-table-footer` are rows themselves). It wraps a set of `mds-table-cell` children, and optionally exposes a per-row selection checkbox and an aside actions menu.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-table-row>` must be slotted inside the `mds-table-body` of an `<mds-table>`; it is not used standalone and its default slot must contain `mds-table-cell` elements, not arbitrary markup.\n- **Parent-driven configuration**: `interactive`, `selectable`, and `overlayActions` are set by the parent `<mds-table>` on every row, so rows stay in sync with table state rather than being configured one by one.\n- **Selection reporting**: When `selectable` is on, the row renders a leading selection checkbox; toggling it updates the row's `selected` prop and tells the table to recompute and emit the table-level selection event.\n- **Selected as two-way state**: `selected` can be read and set by the parent to drive bulk select-all behavior.\n- **Actions menu**: An `action`-named slot, when present, renders an actions cell that floats correctly over the scrolling row.\n- **Localized accessibility labels**: The selection switch's title is localized (Select/Deselect row) across el/en/es/it.\n\n#### Properties & Visual Configurations\n\nMost props are orchestrated by the parent table rather than set directly by consumers:\n\n- **`interactive`**: mirrors the table's interactive mode (hover highlight); normally inherited from `<mds-table>` rather than set per row.\n- **`selectable`**: enables the leading selection switch; toggled by the table so all rows gain or lose selection together.\n- **`overlayActions`**: set by the table when the row content overflows horizontally, switching the actions menu to an overlay rendering so it stays reachable while scrolling.\n- **`selected`**: the row's current selection state; read and written by the parent for select-all and batch operations
|
|
32371
|
+
"1. Description": "The `<mds-table-row>` web component represents a single data row inside a [`<mds-table>`](../mds-table/AGENTS.md) (slotted through `mds-table-body`; `mds-table-header` and `mds-table-footer` are rows themselves). It wraps a set of `mds-table-cell` children, and optionally exposes a per-row selection checkbox and an aside actions menu.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-table-row>` must be slotted inside the `mds-table-body` of an `<mds-table>`; it is not used standalone and its default slot must contain `mds-table-cell` elements, not arbitrary markup.\n- **Parent-driven configuration**: `interactive`, `selectable`, and `overlayActions` are set by the parent `<mds-table>` on every row, so rows stay in sync with table state rather than being configured one by one.\n- **Selection reporting**: When `selectable` is on, the row renders a leading selection checkbox; toggling it updates the row's `selected` prop and tells the table to recompute and emit the table-level selection event.\n- **Selected as two-way state**: `selected` can be read and set by the parent to drive bulk select-all behavior.\n- **Actions menu**: An `action`-named slot, when present, renders an actions cell that floats correctly over the scrolling row.\n- **Localized accessibility labels**: The selection switch's title is localized (Select/Deselect row) across el/en/es/it.\n\n#### Properties & Visual Configurations\n\nMost props are orchestrated by the parent table rather than set directly by consumers:\n\n- **`interactive`**: mirrors the table's interactive mode (hover highlight); normally inherited from `<mds-table>` rather than set per row.\n- **`selectable`**: enables the leading selection switch; toggled by the table so all rows gain or lose selection together.\n- **`overlayActions`**: set by the table when the row content overflows horizontally, switching the actions menu to an overlay rendering so it stays reachable while scrolling.\n- **`selected`**: the row's current selection state; read and written by the parent for select-all and batch operations. Write it in the markup for a row that starts selected: the table counts it on load, without an `mdsTableSelectionChange`.\n- **`value`**: the identifying payload reported back in the table's selection event for this row - set this to the business key (e.g. record id) you need when handling selections.\n",
|
|
32015
32372
|
"2. Examples": "Correct and idiomatic ways to use the `<mds-table-row>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Basic Row with Data Cells\n\nThe minimal form: slot one or more [`mds-table-cell`](../mds-table-cell/AGENTS.md) elements into the default slot. Always place `<mds-table-row>` inside [`mds-table-body`](../mds-table-body/AGENTS.md) - never standalone, and never inside `mds-table-header` / `mds-table-footer`, which are rows themselves.\n\n```html\n<mds-table>\n <mds-table-header>\n <mds-table-header-cell label=\"Nome\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Email\"></mds-table-header-cell>\n <mds-table-header-cell label=\"Data\"></mds-table-header-cell>\n </mds-table-header>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">mario.rossi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">12 ottobre 1985</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Luigi Verdi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">luigi.verdi@example.com</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">3 marzo 1993</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Row with Per-Row Actions\n\nSlot one or more [`mds-button`](../mds-button/AGENTS.md) elements into the `action` slot to add a contextual actions menu that slides in on row hover. Use icon-only buttons with `aria-label` (or `title`) because the label has no space.\n\n```html\n<mds-table-row value=\"42\">\n <mds-table-cell><mds-text typography=\"detail\">Documento riservato.pdf</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">2 MB</mds-text></mds-table-cell>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/download\"\n title=\"Scarica\"\n variant=\"primary\"\n tone=\"text\"\n ></mds-button>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/delete\"\n title=\"Elimina\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n</mds-table-row>\n```\n\n#### Row with Identifying `value`\n\nSet `value` to the business key (record id or slug) that the parent table should include in the `mdsTableSelectionChange` event detail. This wires the visual row to the data layer without any manual DOM traversal.\n\n```html\n<mds-table selectable>\n <mds-table-body>\n <mds-table-row value=\"user-101\">\n <mds-table-cell><mds-text typography=\"detail\">Carla Bianchi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">carla.bianchi@example.com</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"user-102\">\n <mds-table-cell><mds-text typography=\"detail\">Federica Neri</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">federica.neri@example.com</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Selectable Table - Reading the Selection Event\n\nWhen the parent `<mds-table>` sets `selectable`, each row renders a leading checkbox automatically. Listen for `mdsTableSelectionChange` on the table - do not wire per-row events.\n\n```html\n<mds-table id=\"utenti\" selectable>\n <mds-table-body>\n <mds-table-row value=\"101\">\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"102\">\n <mds-table-cell><mds-text typography=\"detail\">Luigi Verdi</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n document.getElementById('utenti').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n });\n</script>\n```\n\n#### Programmatic Selection\n\n`selected` is mutable and reflected. Set it from JavaScript to restore a previously saved selection state. The parent table follows it: it emits `mdsTableSelectionChange` and updates the header checkbox and the batch-action bar, once for the rows changed together. For bulk \"select all\" use the table's `selectAll()`.\n\n```html\n<mds-table selectable id=\"tabella-record\">\n <mds-table-body>\n <mds-table-row id=\"riga-principale\" value=\"rec-1\">\n <mds-table-cell><mds-text typography=\"detail\">Record principale</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<script>\n // Select the row programmatically (e.g. after restoring from storage)\n document.getElementById('riga-principale').selected = true;\n</script>\n```\n\n#### Interactive Table (Hover Highlight)\n\nSet `interactive` on the parent `<mds-table>` to enable per-row hover highlights. The prop is mirrored to each row by the table - do not set it on individual rows.\n\n```html\n<mds-table interactive>\n <mds-table-body>\n <mds-table-row value=\"p-01\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica 01</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">In lavorazione</mds-text></mds-table-cell>\n </mds-table-row>\n <mds-table-row value=\"p-02\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica 02</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">Completata</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Styling Customization\n\nA row takes its colours from the parent `mds-table-body` (and `mds-table`), and its hover, selected and sorted colours and the spacing of its actions follow its states. Restyle the rows through the public `--mds-table-body-*` or `--mds-table-*` properties of the parents. Use the semantic color roles wrapped in `rgb(var(--magma-<role>))` so dark mode and high-contrast modes stay consistent.\n\n```css\n/* Branded colours for the rows of a table */\n.tabella-brand mds-table-body {\n --mds-table-body-background: rgb(var(--magma-surface-raised));\n --mds-table-body-color: rgb(var(--magma-text-default));\n}\n```\n\nThe one public custom property of the row, `--mds-table-row-actions-background`, is read-only: it is the background the actions box paints in the current state of the row (at rest, on hover, while a column sorts a selectable table). Content of the `action` slot reads it to paint the same colour when it moves out of the box, for example a status that follows the part of a tall row on screen. Read it, never set it: the box sets it itself, so a value set from outside changes nothing.\n\n```html\n<mds-table interactive>\n <mds-table-body>\n <mds-table-row value=\"p-01\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica 01</mds-text></mds-table-cell>\n <mds-text slot=\"action\" typography=\"detail\" class=\"bg-(--mds-table-row-actions-background)\">Copiato</mds-text>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n",
|
|
32016
32373
|
"3. Mistakes": "Common incorrect uses of `<mds-table-row>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-table-row>` Standalone\n\n`<mds-table-row>` is a compound child component and must be slotted inside the [`mds-table-body`](../mds-table-body/AGENTS.md) of an [`mds-table`](../mds-table/AGENTS.md). Using it outside the table subtree breaks layout and the internal parent-child communication that drives selection and interactive state.\n\n```html\n<!-- INCORRECT -->\n<div class=\"my-list\">\n <mds-table-row>\n <mds-table-cell>Mario Rossi</mds-table-cell>\n </mds-table-row>\n</div>\n\n<!-- CORRECT -->\n<mds-table>\n <mds-table-body>\n <mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Do Not Put Arbitrary HTML in the Default Slot\n\nThe default slot of `<mds-table-row>` accepts only [`mds-table-cell`](../mds-table-cell/AGENTS.md) elements. Slotting raw `<td>`, `<div>`, or other markup breaks the table layout model and the sort/selection logic that relies on `mds-table-cell` identity.\n\n```html\n<!-- INCORRECT -->\n<mds-table-row>\n <td>Mario Rossi</td>\n <div>mario.rossi@example.com</div>\n</mds-table-row>\n\n<!-- CORRECT -->\n<mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Mario Rossi</mds-text></mds-table-cell>\n <mds-table-cell><mds-text typography=\"detail\">mario.rossi@example.com</mds-text></mds-table-cell>\n</mds-table-row>\n```\n\n#### Do Not Set `interactive` or `selectable` Directly on Individual Rows\n\nBoth props are orchestrated by the parent `<mds-table>` and propagated to every row automatically. Setting them per-row creates a desynchronized state where some rows behave differently from others, and the table's own state machine does not know about the override.\n\n```html\n<!-- INCORRECT -->\n<mds-table>\n <mds-table-body>\n <mds-table-row interactive selectable>\n <mds-table-cell><mds-text typography=\"detail\">Pratica 01</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n\n<!-- CORRECT -->\n<mds-table interactive selectable>\n <mds-table-body>\n <mds-table-row value=\"p-01\">\n <mds-table-cell><mds-text typography=\"detail\">Pratica 01</mds-text></mds-table-cell>\n </mds-table-row>\n </mds-table-body>\n</mds-table>\n```\n\n#### Do Not Listen for Row Events to Track Selection - Use the Table Event\n\n`<mds-table-row>` does not emit a public selection event. The table-level `mdsTableSelectionChange` event is the single aggregated source of truth for which rows are selected. Polling each row's `selected` attribute via MutationObserver or querying the DOM on every click is fragile and bypasses the table's own selection bookkeeping.\n\n```html\n<!-- INCORRECT -->\n<script>\n document.querySelectorAll('mds-table-row').forEach((row) => {\n row.addEventListener('click', () => {\n console.log('selezionato:', row.selected);\n });\n });\n</script>\n\n<!-- CORRECT -->\n<script>\n document.querySelector('mds-table').addEventListener('mdsTableSelectionChange', (e) => {\n console.log('Righe selezionate:', e.detail.rows);\n });\n</script>\n```\n\n#### Do Not Slot Icon-Only Action Buttons Without an Accessible Name\n\nButtons in the `action` slot render without visible labels. An `<mds-button>` that has neither `label` nor `aria-label` / `title` falls back to the last segment of its icon slug (`delete`), which names the icon, not the action. Always provide `title` or `aria-label` on every action button.\n\n```html\n<!-- INCORRECT -->\n<mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Documento.pdf</mds-text></mds-table-cell>\n <mds-button slot=\"action\" icon=\"mi/baseline/delete\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-table-row>\n\n<!-- CORRECT -->\n<mds-table-row>\n <mds-table-cell><mds-text typography=\"detail\">Documento.pdf</mds-text></mds-table-cell>\n <mds-button\n slot=\"action\"\n icon=\"mi/baseline/delete\"\n title=\"Elimina documento\"\n variant=\"error\"\n tone=\"text\"\n ></mds-button>\n</mds-table-row>\n```\n\n#### Do Not Override Row Appearance with Inline Styles or Undocumented Selectors\n\n`mds-table-row` has no public CSS custom property and no shadow part: restyle the rows through the public `--mds-table-body-*` or `--mds-table-*` properties of the parents. Targeting internal shadow parts or setting `background-color` / `color` directly on the host element bypasses the interactive and selected state logic and will break on minor releases.\n\n```css\n/* INCORRECT */\nmds-table-row {\n background-color: rgb(var(--magma-surface-raised));\n color: rgb(var(--magma-text-default));\n}\nmds-table-row::part(actions) {\n gap: 4px;\n}\n\n/* CORRECT */\nmds-table-body {\n --mds-table-body-background: rgb(var(--magma-surface-raised));\n --mds-table-body-color: rgb(var(--magma-text-default));\n}\n```\n"
|
|
32017
32374
|
},
|
|
@@ -36028,9 +36385,9 @@
|
|
|
36028
36385
|
}
|
|
36029
36386
|
],
|
|
36030
36387
|
"usage": {
|
|
36031
|
-
"1. Description": "The `<mds-zero>` web component is the empty-state (zero-data) panel of the Magma Design System: a centered, vertically stacked layout that pairs an illustration, explanatory copy, and a call-to-action to guide users when a list, search, or section has no content to show. It is a pure structural container with no props - composition happens entirely through its slots.\n\n#### Semantic Behavior\n\n- **Three-zone layout**: The host stacks its content vertically and centered - the default slot (the visual) on top, the `content` zone in the middle, and the `action` zone in a footer at the bottom.\n- **Default slot is the visual**: The unnamed default slot holds the illustration or image; it is meant for an `mds-img`/`img`, not text.\n- **Content zone is centered text**: The `content` slot is centered
|
|
36032
|
-
"2. Examples": "Correct and idiomatic ways to use the `<mds-zero>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md).\n\n#### Full Empty-State Panel\n\nThe canonical form
|
|
36033
|
-
"3. Mistakes": "Common incorrect uses of `<mds-zero>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Put Text in the Default Slot\n\nThe default slot is reserved for the illustration or image. Text placed there is not constrained by the `contents` max-width, is not centered consistently, and falls outside the structured three-zone layout. Put headings and descriptions in `slot=\"content\"`.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-text typography=\"
|
|
36388
|
+
"1. Description": "The `<mds-zero>` web component is the empty-state (zero-data) panel of the Magma Design System: a centered, vertically stacked layout that pairs an illustration, explanatory copy, and a call-to-action to guide users when a list, search, or section has no content to show. It is a pure structural container with no props - composition happens entirely through its slots.\n\n#### Semantic Behavior\n\n- **Three-zone layout**: The host stacks its content vertically and centered - the default slot (the visual) on top, the `content` zone in the middle, and the `action` zone in a footer at the bottom - with `--magma-rhythm-content-actions` (600) between the zones.\n- **One inset, shared by the zones**: The host pads its zones once, with `--magma-rhythm-inset` (600) on every side, the inset of a container of a part (`rhythm/inset`, `rhythm/shared-inset` in the design language). With no action the footer takes no room, so the inset stays the same at the bottom.\n- **Default slot is the visual**: The unnamed default slot holds the illustration or image; it is meant for an `mds-img`/`img`, not text.\n- **Content zone is centered text**: The `content` slot is centered, constrained by a max-width, and sets its children `--magma-rhythm-title-content` (300) apart, so a title and its description read as one message with no wrapper of yours (`rhythm/title-content`).\n- **Action zone auto-centers children**: Elements placed in `slot=\"action\"` are horizontally centered within the footer, `--magma-rhythm-inline` (300) apart, so a single primary button sits centered by default.\n- **A muted surface**: The host paints `--magma-surface-muted`, a step under the page in light and in dark, on the plane where the items would stand; it needs no dark correction, and it picks up the contrast (a ring) and reduced-motion preferences.\n\n#### Properties & Visual Configurations\n\n`<mds-zero>` exposes no props; all configuration is done through slot composition and one CSS custom property.\n\n- **`content` vs. `action` slots**: Put the message in `slot=\"content\"`: a title by its role, `mds-text typography=\"part\"` with the `tag` of its place in the outline (`h2` under the title of the page, `h3` in a section, `h1` with `typography=\"page\"` when the panel takes the place of the page), then the description in `typography=\"detail\"`. Put the recovery action (typically a single `mds-button`) in `slot=\"action\"`. Use the default slot only for the illustration.\n- **`--mds-zero-contents-max-width`**: Caps the width of the centered text block (default `400px`) so long descriptions wrap into a balanced column rather than spanning the full panel.\n\nThe `contents` and `actions` shadow parts expose the two wrapper zones for consumers that need to override their layout from outside the shadow boundary.\n",
|
|
36389
|
+
"2. Examples": "Correct and idiomatic ways to use the `<mds-zero>` component, ordered from most common to most specialized. The examples assume a working knowledge of the shared component rules in [`agents/conventions.md`](../../../../agents/conventions.md). Which panel an empty part takes, and what it says, is the pattern `empty-state`.\n\nThe title of the panel is written by its role, `typography=\"part\"` (`titles/part` of the design language), with the `tag` of its place in the outline: `h2` under the title of the page, `h3` inside a section. Put the title and the description straight in `slot=\"content\"`: the panel sets them apart itself.\n\n#### Full Empty-State Panel\n\nThe canonical form, the first use: an illustration in the default slot, a title and a description in `slot=\"content\"`, and the action that adds the first item in `slot=\"action\"`.\n\n```html\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty-list.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessuna delega</mds-text>\n <mds-text typography=\"detail\" tag=\"p\" slot=\"content\">\n Con una delega un familiare o un professionista presenta le richieste a tuo nome.\n Aggiungi la prima per iniziare.\n </mds-text>\n <mds-button\n slot=\"action\"\n label=\"Nuova delega\"\n variant=\"primary\"\n tone=\"strong\"\n size=\"lg\"\n ></mds-button>\n</mds-zero>\n```\n\n#### Filled by Others (No Action)\n\nWhen the person has nothing to do here, omit `slot=\"action\"` entirely and say who fills the part, and when. The action zone takes no room, so the inset stays the same on every side.\n\n```html\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty-folder.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun documento</mds-text>\n <mds-text typography=\"detail\" tag=\"p\" slot=\"content\">\n L'ufficio anagrafe aggiunge qui i documenti della pratica quando la prende in carico.\n </mds-text>\n</mds-zero>\n```\n\n#### Message Without Illustration\n\nWhen no illustration asset is available, omit the default slot. The component stacks the content and action zones directly.\n\n```html\n<mds-zero>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun file</mds-text>\n <mds-text typography=\"detail\" tag=\"p\" slot=\"content\">\n Carica i tuoi file per iniziare a condividerli con il team.\n </mds-text>\n <mds-button\n slot=\"action\"\n label=\"Carica file\"\n icon=\"mi/baseline/upload\"\n variant=\"primary\"\n tone=\"strong\"\n ></mds-button>\n</mds-zero>\n```\n\n#### Multiple Actions\n\nWhen two peer actions are offered - for example a primary and a secondary CTA - place both `<mds-button>` elements in `slot=\"action\"`. The action zone centers them and sets them `--magma-rhythm-inline` apart.\n\n```html\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty-inbox.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun messaggio</mds-text>\n <mds-text typography=\"detail\" tag=\"p\" slot=\"content\">\n Inizia una nuova conversazione o invita i tuoi colleghi.\n </mds-text>\n <mds-button\n slot=\"action\"\n label=\"Nuovo messaggio\"\n variant=\"primary\"\n tone=\"strong\"\n ></mds-button>\n <mds-button\n slot=\"action\"\n label=\"Invita colleghi\"\n variant=\"primary\"\n tone=\"outline\"\n ></mds-button>\n</mds-zero>\n```\n\n#### In Place of a Missing Page\n\nWhen the panel takes the place of the whole page (the thing asked for does not exist), its title is the title of the page: `typography=\"page\"` with `tag=\"h1\"`, and its action leads back to the list.\n\n```html\n<main class=\"page-frame py-between-sections\">\n <mds-zero>\n <mds-text typography=\"page\" tag=\"h1\" slot=\"content\">Richiesta non trovata</mds-text>\n <mds-text typography=\"detail\" tag=\"p\" slot=\"content\">\n La richiesta 2026/0412 non esiste: cercala nell'elenco delle richieste.\n </mds-text>\n <mds-button slot=\"action\" label=\"Vai alle richieste\" href=\"/richieste\"></mds-button>\n </mds-zero>\n</main>\n```\n\n#### Constraining the Text Block Width\n\nUse `--mds-zero-contents-max-width` when the panel is wide and the default `400px` cap produces too narrow a text column, or when you want a tighter column on a compact layout.\n\n```css\n.wide-dashboard mds-zero {\n --mds-zero-contents-max-width: 560px;\n}\n\n.compact-sidebar mds-zero {\n --mds-zero-contents-max-width: 280px;\n}\n```\n\n#### Overriding Zone Layout via Shadow Parts\n\nUse `::part(contents)` or `::part(actions)` only when you need to change the zone's layout itself - for example aligning the content left inside a side-panel context. Prefer `--mds-zero-contents-max-width` for width adjustments.\n\n```css\n/* Left-align content for a narrow side panel */\n.side-panel mds-zero::part(contents) {\n align-items: flex-start;\n text-align: left;\n}\n```\n",
|
|
36390
|
+
"3. Mistakes": "Common incorrect uses of `<mds-zero>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`agents/mistakes.md`](../../../../agents/mistakes.md) - they apply here too but are not repeated.\n\n#### Do Not Put Text in the Default Slot\n\nThe default slot is reserved for the illustration or image. Text placed there is not constrained by the `contents` max-width, is not centered consistently, and falls outside the structured three-zone layout. Put headings and descriptions in `slot=\"content\"`.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-text typography=\"part\" tag=\"h2\">Nessun elemento</mds-text>\n <mds-text typography=\"detail\">Crea il primo elemento per iniziare.</mds-text>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun elemento</mds-text>\n <mds-text typography=\"detail\" slot=\"content\">Crea il primo elemento per iniziare.</mds-text>\n</mds-zero>\n```\n\n#### Do Not Title the Panel by Level\n\nA level picked by its size (`h5`, `h6`) says nothing of what the title names, and its tag follows the style instead of the outline of the page. The title of the panel is a part (`titles/part` of the design language): `typography=\"part\"`, with the `tag` of its place, `h2` under the title of the page, `h3` in a section.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-text typography=\"h5\" slot=\"content\">Nessuna richiesta da gestire</mds-text>\n <mds-text typography=\"detail\" slot=\"content\">Le nuove arrivano qui appena un cittadino le invia.</mds-text>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessuna richiesta da gestire</mds-text>\n <mds-text typography=\"detail\" tag=\"p\" slot=\"content\">Le nuove arrivano qui appena un cittadino le invia.</mds-text>\n</mds-zero>\n```\n\n#### Do Not Wrap the Content to Space It\n\nThe content zone already sets its children `--magma-rhythm-title-content` apart. A wrapper with its own gap adds nothing but a second place where the space is decided; put the title and the description straight in `slot=\"content\"`.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <div slot=\"content\" class=\"grid gap-title-content\">\n <mds-text typography=\"part\" tag=\"h2\">Nessuna delega</mds-text>\n <mds-text typography=\"detail\" tag=\"p\">Aggiungi la prima per iniziare.</mds-text>\n </div>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessuna delega</mds-text>\n <mds-text typography=\"detail\" tag=\"p\" slot=\"content\">Aggiungi la prima per iniziare.</mds-text>\n</mds-zero>\n```\n\n#### Do Not Put the Illustration in `slot=\"content\"`\n\nPlacing an image or `<mds-img>` inside `slot=\"content\"` wraps it in the max-width-constrained, centered-text zone. The default slot renders above that zone with full layout freedom and is the correct home for illustrations.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\" slot=\"content\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun documento</mds-text>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun documento</mds-text>\n</mds-zero>\n```\n\n#### Do Not Put the CTA in `slot=\"content\"`\n\nA button placed in `slot=\"content\"` ends up inside the centered-text block rather than the footer zone; it loses the auto-centering and the correct spacing the `actions` zone provides. Use `slot=\"action\"` for any interactive control.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun progetto</mds-text>\n <mds-button label=\"Nuovo progetto\" variant=\"primary\" slot=\"content\"></mds-button>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun progetto</mds-text>\n <mds-button label=\"Nuovo progetto\" variant=\"primary\" slot=\"action\"></mds-button>\n</mds-zero>\n```\n\n#### Do Not Use a Raw `<button>` or `<a>` in the Action Slot\n\nThe action slot is designed for `<mds-button>`. A raw `<button>` or `<a>` will not inherit Magma theming, focus styles, or size tokens. Use `<mds-button>` with `href` if link behavior is needed.\n\n```html\n<!-- INCORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun report</mds-text>\n <button slot=\"action\" class=\"btn-primary\">Crea report</button>\n</mds-zero>\n\n<!-- CORRECT -->\n<mds-zero>\n <mds-img src=\"./assets/illustrations/empty.svg\" alt=\"\"></mds-img>\n <mds-text typography=\"part\" tag=\"h2\" slot=\"content\">Nessun report</mds-text>\n <mds-button slot=\"action\" label=\"Crea report\" variant=\"primary\" tone=\"strong\"></mds-button>\n</mds-zero>\n```\n\n#### Do Not Pierce Shadow DOM to Style Internal Zones\n\n`::part(contents)` and `::part(actions)` are the documented customization surface for the wrapper zones. Do not target internal class names (`.contents`, `.actions`) via `>>>` or `/deep/` - those are implementation details that can change without notice.\n\n```css\n/* INCORRECT */\nmds-zero >>> .contents {\n max-width: 600px;\n}\n\n/* CORRECT */\nmds-zero {\n --mds-zero-contents-max-width: 600px;\n}\n/* or, for layout overrides: */\nmds-zero::part(contents) {\n align-items: flex-start;\n}\n```\n"
|
|
36034
36391
|
},
|
|
36035
36392
|
"props": [],
|
|
36036
36393
|
"methods": [],
|
|
@@ -36097,7 +36454,7 @@
|
|
|
36097
36454
|
"path": "src/type/tone.ts"
|
|
36098
36455
|
},
|
|
36099
36456
|
"src/type/text.ts::TypographyTruncateType": {
|
|
36100
|
-
"declaration": "\"
|
|
36457
|
+
"declaration": "\"all\" | \"none\" | \"word\"",
|
|
36101
36458
|
"docstring": "",
|
|
36102
36459
|
"path": "src/type/text.ts"
|
|
36103
36460
|
},
|
|
@@ -36116,6 +36473,11 @@
|
|
|
36116
36473
|
"docstring": "",
|
|
36117
36474
|
"path": "src/type/typography.ts"
|
|
36118
36475
|
},
|
|
36476
|
+
"src/type/text.ts::TypographyHeadingTagType": {
|
|
36477
|
+
"declaration": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\"",
|
|
36478
|
+
"docstring": "",
|
|
36479
|
+
"path": "src/type/text.ts"
|
|
36480
|
+
},
|
|
36119
36481
|
"src/components/mds-accordion-item/meta/event-detail.ts::MdsAccordionItemEventDetail": {
|
|
36120
36482
|
"declaration": "export interface MdsAccordionItemEventDetail {\n id: string;\n selected: boolean;\n}",
|
|
36121
36483
|
"docstring": "",
|
|
@@ -36166,6 +36528,11 @@
|
|
|
36166
36528
|
"docstring": "",
|
|
36167
36529
|
"path": "src/type/tone.ts"
|
|
36168
36530
|
},
|
|
36531
|
+
"src/components/mds-banner/meta/types.ts::BannerTypographyType": {
|
|
36532
|
+
"declaration": "\"h5\" | \"h6\"",
|
|
36533
|
+
"docstring": "",
|
|
36534
|
+
"path": "src/components/mds-banner/meta/types.ts"
|
|
36535
|
+
},
|
|
36169
36536
|
"src/components/mds-benchmark-bar/meta/types.ts::BenchmarkBarTypographyType": {
|
|
36170
36537
|
"declaration": "export type BenchmarkBarTypographyType = 'option' | 'label';",
|
|
36171
36538
|
"docstring": "",
|
|
@@ -36276,6 +36643,11 @@
|
|
|
36276
36643
|
"docstring": "",
|
|
36277
36644
|
"path": "src/type/button.ts"
|
|
36278
36645
|
},
|
|
36646
|
+
"src/components/mds-calendar/meta/types.ts::CalendarRangeEndType": {
|
|
36647
|
+
"declaration": "export type CalendarRangeEndType = 'start' | 'end';",
|
|
36648
|
+
"docstring": "",
|
|
36649
|
+
"path": "src/components/mds-calendar/meta/types.ts"
|
|
36650
|
+
},
|
|
36279
36651
|
"src/components/mds-calendar-cell/meta/types.ts::CalendarCellType": {
|
|
36280
36652
|
"declaration": "export type CalendarCellType = 'other' | 'current' | 'weekend';",
|
|
36281
36653
|
"docstring": "",
|
|
@@ -36352,12 +36724,12 @@
|
|
|
36352
36724
|
"path": "src/components/mds-filter-item/meta/event-detail.ts"
|
|
36353
36725
|
},
|
|
36354
36726
|
"src/type/header-bar.ts::HeaderBarMenuType": {
|
|
36355
|
-
"declaration": "\"
|
|
36727
|
+
"declaration": "\"all\" | \"none\" | \"desktop\" | \"mobile\"",
|
|
36356
36728
|
"docstring": "",
|
|
36357
36729
|
"path": "src/type/header-bar.ts"
|
|
36358
36730
|
},
|
|
36359
36731
|
"src/type/header-bar.ts::HeaderBarNavType": {
|
|
36360
|
-
"declaration": "\"
|
|
36732
|
+
"declaration": "\"all\" | \"none\" | \"desktop\" | \"mobile\"",
|
|
36361
36733
|
"docstring": "",
|
|
36362
36734
|
"path": "src/type/header-bar.ts"
|
|
36363
36735
|
},
|
|
@@ -36422,7 +36794,7 @@
|
|
|
36422
36794
|
"path": "src/type/variant.ts"
|
|
36423
36795
|
},
|
|
36424
36796
|
"src/type/input.ts::InputTextType": {
|
|
36425
|
-
"declaration": "\"number\" | \"
|
|
36797
|
+
"declaration": "\"number\" | \"time\" | \"text\" | \"email\" | \"tel\" | \"url\" | \"date\" | \"password\" | \"search\" | \"textarea\" | \"color\" | \"cc\" | \"cf\" | \"isbn\" | \"piva\"",
|
|
36426
36798
|
"docstring": "",
|
|
36427
36799
|
"path": "src/type/input.ts"
|
|
36428
36800
|
},
|
|
@@ -36451,6 +36823,11 @@
|
|
|
36451
36823
|
"docstring": "",
|
|
36452
36824
|
"path": "src/components.d.ts"
|
|
36453
36825
|
},
|
|
36826
|
+
"src/components/mds-input-range/meta/event-detail.ts::MdsInputRangeValuesEventDetail": {
|
|
36827
|
+
"declaration": "export interface MdsInputRangeValuesEventDetail {\n /**\n * The values of the `mds-input-range-value` children, one per thumb, in order from the lowest:\n * the order of their thumbs on the track and of their entries in the form.\n */\n values: number[];\n}",
|
|
36828
|
+
"docstring": "",
|
|
36829
|
+
"path": "src/components/mds-input-range/meta/event-detail.ts"
|
|
36830
|
+
},
|
|
36454
36831
|
"src/type/variant.ts::ThemeStatusVariantType": {
|
|
36455
36832
|
"declaration": "\"info\" | \"error\" | \"success\" | \"warning\"",
|
|
36456
36833
|
"docstring": "",
|
|
@@ -36612,7 +36989,7 @@
|
|
|
36612
36989
|
"path": "src/type/preference.ts"
|
|
36613
36990
|
},
|
|
36614
36991
|
"src/type/preference.ts::PreferenceThemeSchemeType": {
|
|
36615
|
-
"declaration": "\"
|
|
36992
|
+
"declaration": "\"all\" | \"dark\" | \"light\"",
|
|
36616
36993
|
"docstring": "",
|
|
36617
36994
|
"path": "src/type/preference.ts"
|
|
36618
36995
|
},
|
|
@@ -36661,11 +37038,6 @@
|
|
|
36661
37038
|
"docstring": "",
|
|
36662
37039
|
"path": "src/components/mds-push-notification-item/meta/event-detail.ts"
|
|
36663
37040
|
},
|
|
36664
|
-
"src/type/text.ts::TypographyHeadingTagType": {
|
|
36665
|
-
"declaration": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\"",
|
|
36666
|
-
"docstring": "",
|
|
36667
|
-
"path": "src/type/text.ts"
|
|
36668
|
-
},
|
|
36669
37041
|
"src/components/mds-radial-menu/meta/types.ts::Direction": {
|
|
36670
37042
|
"declaration": "export type Direction = 'clockwise' | 'counterclockwise';",
|
|
36671
37043
|
"docstring": "",
|
|
@@ -36767,7 +37139,7 @@
|
|
|
36767
37139
|
"path": "src/components/mds-table-header-cell/meta/event-detail.ts"
|
|
36768
37140
|
},
|
|
36769
37141
|
"src/type/text.ts::TypographyTagType": {
|
|
36770
|
-
"declaration": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | \"label\" | \"code\" | \"
|
|
37142
|
+
"declaration": "\"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | \"label\" | \"code\" | \"abbr\" | \"address\" | \"article\" | \"b\" | \"bdo\" | \"blockquote\" | \"cite\" | \"dd\" | \"del\" | \"details\" | \"dfn\" | \"div\" | \"dl\" | \"dt\" | \"em\" | \"figcaption\" | \"i\" | \"ins\" | \"kbd\" | \"legend\" | \"li\" | \"mark\" | \"ol\" | \"p\" | \"pre\" | \"q\" | \"rb\" | \"rt\" | \"ruby\" | \"s\" | \"samp\" | \"small\" | \"span\" | \"strong\" | \"sub\" | \"summary\" | \"sup\" | \"time\" | \"u\" | \"ul\" | \"var\"",
|
|
36771
37143
|
"docstring": "",
|
|
36772
37144
|
"path": "src/type/text.ts"
|
|
36773
37145
|
},
|
|
@@ -36827,5 +37199,6 @@
|
|
|
36827
37199
|
"path": "src/components/mds-video-wall/meta/types.ts"
|
|
36828
37200
|
}
|
|
36829
37201
|
},
|
|
36830
|
-
"storybook": "https://magma-design-system.github.io/magma/storybook/"
|
|
37202
|
+
"storybook": "https://magma-design-system.github.io/magma/storybook/",
|
|
37203
|
+
"studio": "https://magma-design-system.github.io/magma/studio/"
|
|
36831
37204
|
}
|