@momentum-design/components 0.129.22 → 0.129.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/dist/browser/index.js +49 -46
  2. package/dist/browser/index.js.map +2 -2
  3. package/dist/components/formfieldwrapper/formfieldwrapper.component.d.ts +5 -3
  4. package/dist/components/formfieldwrapper/formfieldwrapper.component.js +4 -2
  5. package/dist/components/statictoggle/statictoggle.component.d.ts +24 -23
  6. package/dist/components/statictoggle/statictoggle.component.js +24 -23
  7. package/dist/components/statictoggle/statictoggle.styles.js +37 -37
  8. package/dist/components/toggle/toggle.component.d.ts +30 -19
  9. package/dist/components/toggle/toggle.component.js +30 -19
  10. package/dist/components/toggle/toggle.styles.js +12 -9
  11. package/dist/components/toggle/toggle.types.d.ts +3 -2
  12. package/dist/custom-elements.json +199 -303
  13. package/dist/index.d.ts +2 -1
  14. package/dist/react/statictoggle/index.d.ts +13 -15
  15. package/dist/react/statictoggle/index.js +13 -15
  16. package/dist/react/toggle/index.d.ts +18 -15
  17. package/dist/react/toggle/index.js +18 -15
  18. package/package.json +1 -1
package/dist/components/formfieldwrapper/formfieldwrapper.component.d.ts CHANGED
@@ -66,17 +66,19 @@ declare class FormfieldWrapper extends FormfieldWrapper_base {
66
66
  */
67
67
  helpText?: string;
68
68
  /**
69
- * The toggletip text that is displayed when the label is hovered.
69
+ * The toggletip text that is displayed when the info icon is clicked or pressed.
70
70
  * It is used to provide additional information about the label.
71
71
  */
72
72
  toggletipText?: string;
73
73
  /**
74
- * The placement of the toggletip that is displayed when the info icon is hovered.
74
+ * The placement of the toggletip that is displayed when the info icon is clicked or pressed.
75
75
  * @default 'top'
76
76
  */
77
77
  toggletipPlacement: PopoverPlacement;
78
78
  /**
79
- * The strategy of the toggletip that is displayed when the info icon is hovered.
79
+ * The positioning strategy for the toggletip.
80
+ * - **absolute**: Positioned relative to the nearest positioned ancestor.
81
+ * - **fixed**: Positioned relative to the viewport.
80
82
  * @default 'absolute'
81
83
  */
82
84
  toggletipStrategy: PopoverStrategy;
package/dist/components/formfieldwrapper/formfieldwrapper.component.js CHANGED
@@ -74,12 +74,14 @@ class FormfieldWrapper extends DisabledMixin(Component) {
74
74
  */
75
75
  this.helpTextType = DEFAULTS.VALIDATION;
76
76
  /**
77
- * The placement of the toggletip that is displayed when the info icon is hovered.
77
+ * The placement of the toggletip that is displayed when the info icon is clicked or pressed.
78
78
  * @default 'top'
79
79
  */
80
80
  this.toggletipPlacement = DEFAULTS.TOGGLETIP_PLACEMENT;
81
81
  /**
82
- * The strategy of the toggletip that is displayed when the info icon is hovered.
82
+ * The positioning strategy for the toggletip.
83
+ * - **absolute**: Positioned relative to the nearest positioned ancestor.
84
+ * - **fixed**: Positioned relative to the viewport.
83
85
  * @default 'absolute'
84
86
  */
85
87
  this.toggletipStrategy = DEFAULTS.TOGGLETIP_STRATEGY;
package/dist/components/statictoggle/statictoggle.component.d.ts CHANGED
@@ -3,51 +3,52 @@ import { Component } from '../../models';
3
3
  import type { ToggleSize } from './statictoggle.types';
4
4
  declare const StaticToggle_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DisabledMixin").DisabledMixinInterface> & typeof Component;
5
5
  /**
6
- * This is a decorative component that is styled to look as a toggle. <br/>
7
- * It has 5 properties - checked, size, disabled, readonly and soft-disabled. <br/>
8
- * We are using the same styling that has been created for the `mdc-toggle` component.
6
+ * The StaticToggle is a decorative component that visually represents a toggle switch without interactive functionality.
7
+ * It is primarily used for display purposes or as a building block within custom interactive components.
8
+ * This component shares the same visual styling as the interactive `mdc-toggle` component.
9
9
  *
10
10
  * @dependency mdc-icon
11
11
  *
12
12
  * @tagname mdc-statictoggle
13
13
  *
14
- * @slot default - This is a default/unnamed slot
14
+ * @slot - Default slot for slotted content (typically used by parent `mdc-toggle` for the checkbox input).
15
15
  *
16
- * @cssproperty --mdc-toggle-width - The width of the toggle
17
- * @cssproperty --mdc-toggle-height - The height of the toggle
18
- * @cssproperty --mdc-toggle-border-radius - The border radius of the toggle
19
- * @cssproperty --mdc-toggle-border-color - The border color of the toggle
20
- * @cssproperty --mdc-toggle-background-color - The background color of the toggle
21
- * @cssproperty --mdc-toggle-icon-color - The icon color of the toggle
22
- * @cssproperty --mdc-toggle-icon-background-color - The icon background color of the toggle
16
+ * @cssproperty --mdc-statictoggle-width - The width of the static toggle.
17
+ * @cssproperty --mdc-statictoggle-height - The height of the static toggle.
18
+ * @cssproperty --mdc-statictoggle-border-radius - The border radius of the static toggle.
19
+ * @cssproperty --mdc-statictoggle-border-color - The border color of the static toggle.
20
+ * @cssproperty --mdc-statictoggle-background-color - The background color of the static toggle.
21
+ * @cssproperty --mdc-statictoggle-icon-color - The icon color of the static toggle.
22
+ * @cssproperty --mdc-statictoggle-icon-background-color - The icon background color of the static toggle.
23
23
  *
24
- * @csspart slider - The slider part of the toggle
25
- * @csspart toggle-icon - The icon part of the toggle
26
- *
27
- * @slot - Default slot for adding label text.
24
+ * @csspart slider - The slider part of the toggle.
25
+ * @csspart toggle-icon - The icon part of the toggle.
28
26
  */
29
27
  declare class StaticToggle extends StaticToggle_base {
30
28
  /**
31
- * Determines whether the toggle is active or inactive.
29
+ * Controls the visual state of the toggle.
30
+ * When true, the toggle appears in the "on" or "active" state.
31
+ * When false, the toggle appears in the "off" or "inactive" state.
32
32
  * @default false
33
33
  */
34
34
  checked: boolean;
35
35
  /**
36
- * Determines toggle size in rem (height is specified here).
37
- * - **Default**: 1.5
38
- * - **Compact**: 1
36
+ * Specifies the size of the toggle component.
37
+ * - **default**: Standard size with 1.5rem height
38
+ * - **compact**: Smaller size with 1rem height
39
39
  * @default default
40
40
  */
41
41
  size: ToggleSize;
42
42
  /**
43
- * Determines whether the toggle is read-only.
44
- *
43
+ * When true, the toggle appears in a read-only visual state.
44
+ * This is a decorative property that changes the visual appearance only.
45
45
  * @default false
46
46
  */
47
47
  readonly: boolean;
48
48
  /**
49
- * Determines whether the toggle is soft-disabled.
50
- *
49
+ * When true, the toggle appears in a soft-disabled visual state.
50
+ * Soft-disabled elements maintain visual presence but appear non-interactive.
51
+ * This is a decorative property that changes the visual appearance only.
51
52
  * @default false
52
53
  */
53
54
  softDisabled: boolean;
package/dist/components/statictoggle/statictoggle.component.js CHANGED
@@ -14,53 +14,54 @@ import { DisabledMixin } from '../../utils/mixins/DisabledMixin';
14
14
  import { DEFAULTS, ICON_NAME, ICON_SIZE_IN_REM } from './statictoggle.constants';
15
15
  import styles from './statictoggle.styles';
16
16
  /**
17
- * This is a decorative component that is styled to look as a toggle. <br/>
18
- * It has 5 properties - checked, size, disabled, readonly and soft-disabled. <br/>
19
- * We are using the same styling that has been created for the `mdc-toggle` component.
17
+ * The StaticToggle is a decorative component that visually represents a toggle switch without interactive functionality.
18
+ * It is primarily used for display purposes or as a building block within custom interactive components.
19
+ * This component shares the same visual styling as the interactive `mdc-toggle` component.
20
20
  *
21
21
  * @dependency mdc-icon
22
22
  *
23
23
  * @tagname mdc-statictoggle
24
24
  *
25
- * @slot default - This is a default/unnamed slot
25
+ * @slot - Default slot for slotted content (typically used by parent `mdc-toggle` for the checkbox input).
26
26
  *
27
- * @cssproperty --mdc-toggle-width - The width of the toggle
28
- * @cssproperty --mdc-toggle-height - The height of the toggle
29
- * @cssproperty --mdc-toggle-border-radius - The border radius of the toggle
30
- * @cssproperty --mdc-toggle-border-color - The border color of the toggle
31
- * @cssproperty --mdc-toggle-background-color - The background color of the toggle
32
- * @cssproperty --mdc-toggle-icon-color - The icon color of the toggle
33
- * @cssproperty --mdc-toggle-icon-background-color - The icon background color of the toggle
27
+ * @cssproperty --mdc-statictoggle-width - The width of the static toggle.
28
+ * @cssproperty --mdc-statictoggle-height - The height of the static toggle.
29
+ * @cssproperty --mdc-statictoggle-border-radius - The border radius of the static toggle.
30
+ * @cssproperty --mdc-statictoggle-border-color - The border color of the static toggle.
31
+ * @cssproperty --mdc-statictoggle-background-color - The background color of the static toggle.
32
+ * @cssproperty --mdc-statictoggle-icon-color - The icon color of the static toggle.
33
+ * @cssproperty --mdc-statictoggle-icon-background-color - The icon background color of the static toggle.
34
34
  *
35
- * @csspart slider - The slider part of the toggle
36
- * @csspart toggle-icon - The icon part of the toggle
37
- *
38
- * @slot - Default slot for adding label text.
35
+ * @csspart slider - The slider part of the toggle.
36
+ * @csspart toggle-icon - The icon part of the toggle.
39
37
  */
40
38
  class StaticToggle extends DisabledMixin(Component) {
41
39
  constructor() {
42
40
  super(...arguments);
43
41
  /**
44
- * Determines whether the toggle is active or inactive.
42
+ * Controls the visual state of the toggle.
43
+ * When true, the toggle appears in the "on" or "active" state.
44
+ * When false, the toggle appears in the "off" or "inactive" state.
45
45
  * @default false
46
46
  */
47
47
  this.checked = false;
48
48
  /**
49
- * Determines toggle size in rem (height is specified here).
50
- * - **Default**: 1.5
51
- * - **Compact**: 1
49
+ * Specifies the size of the toggle component.
50
+ * - **default**: Standard size with 1.5rem height
51
+ * - **compact**: Smaller size with 1rem height
52
52
  * @default default
53
53
  */
54
54
  this.size = DEFAULTS.SIZE;
55
55
  /**
56
- * Determines whether the toggle is read-only.
57
- *
56
+ * When true, the toggle appears in a read-only visual state.
57
+ * This is a decorative property that changes the visual appearance only.
58
58
  * @default false
59
59
  */
60
60
  this.readonly = false;
61
61
  /**
62
- * Determines whether the toggle is soft-disabled.
63
- *
62
+ * When true, the toggle appears in a soft-disabled visual state.
63
+ * Soft-disabled elements maintain visual presence but appear non-interactive.
64
+ * This is a decorative property that changes the visual appearance only.
64
65
  * @default false
65
66
  */
66
67
  this.softDisabled = false;
package/dist/components/statictoggle/statictoggle.styles.js CHANGED
@@ -2,23 +2,23 @@ import { css } from 'lit';
2
2
  const styles = [
3
3
  css `
4
4
  :host {
5
- --mdc-toggle-width: 3rem;
6
- --mdc-toggle-height: 1.5rem;
7
- --mdc-toggle-border-radius: 0.75rem;
8
- --mdc-toggle-border-color: var(--mds-color-theme-outline-input-normal);
9
- --mdc-toggle-background-color: var(--mds-color-theme-control-inactive-normal);
10
- --mdc-toggle-icon-color: var(--mds-color-theme-common-inverted-text-primary-normal);
11
- --mdc-toggle-icon-background-color: var(--mds-color-theme-common-text-primary-normal);
5
+ --mdc-statictoggle-width: 3rem;
6
+ --mdc-statictoggle-height: 1.5rem;
7
+ --mdc-statictoggle-border-radius: 0.75rem;
8
+ --mdc-statictoggle-border-color: var(--mds-color-theme-outline-input-normal);
9
+ --mdc-statictoggle-background-color: var(--mds-color-theme-control-inactive-normal);
10
+ --mdc-statictoggle-icon-color: var(--mds-color-theme-common-inverted-text-primary-normal);
11
+ --mdc-statictoggle-icon-background-color: var(--mds-color-theme-common-text-primary-normal);
12
12
 
13
- border-radius: var(--mdc-toggle-border-radius);
13
+ border-radius: var(--mdc-statictoggle-border-radius);
14
14
  }
15
15
 
16
16
  :host::part(slider) {
17
- width: var(--mdc-toggle-width);
18
- height: var(--mdc-toggle-height);
19
- background-color: var(--mdc-toggle-background-color);
20
- border: 1px solid var(--mdc-toggle-border-color);
21
- border-radius: var(--mdc-toggle-border-radius);
17
+ width: var(--mdc-statictoggle-width);
18
+ height: var(--mdc-statictoggle-height);
19
+ background-color: var(--mdc-statictoggle-background-color);
20
+ border: 1px solid var(--mdc-statictoggle-border-color);
21
+ border-radius: var(--mdc-statictoggle-border-radius);
22
22
  display: flex;
23
23
  align-items: center;
24
24
  justify-content: flex-start;
@@ -29,15 +29,15 @@ const styles = [
29
29
 
30
30
  :host::part(toggle-icon) {
31
31
  padding: 0.25rem;
32
- --mdc-icon-fill-color: var(--mdc-toggle-icon-color);
33
- background-color: var(--mdc-toggle-icon-background-color);
32
+ --mdc-icon-fill-color: var(--mdc-statictoggle-icon-color);
33
+ background-color: var(--mdc-statictoggle-icon-background-color);
34
34
  border-radius: 50%;
35
35
  }
36
36
 
37
37
  :host([size='compact'])::part(slider) {
38
- --mdc-toggle-width: 2rem;
39
- --mdc-toggle-height: 1rem;
40
- --mdc-toggle-border-radius: 0.5rem;
38
+ --mdc-statictoggle-width: 2rem;
39
+ --mdc-statictoggle-height: 1rem;
40
+ --mdc-statictoggle-border-radius: 0.5rem;
41
41
  }
42
42
 
43
43
  :host([size='compact'])::part(toggle-icon) {
@@ -45,52 +45,52 @@ const styles = [
45
45
  }
46
46
 
47
47
  :host([checked]) {
48
- --mdc-toggle-border-color: transparent;
49
- --mdc-toggle-background-color: var(--mds-color-theme-control-active-normal);
48
+ --mdc-statictoggle-border-color: transparent;
49
+ --mdc-statictoggle-background-color: var(--mds-color-theme-control-active-normal);
50
50
  }
51
51
  :host([checked])::part(slider) {
52
52
  justify-content: flex-end;
53
53
  }
54
54
 
55
55
  :host([readonly]) {
56
- --mdc-toggle-icon-background-color: var(--mds-color-theme-common-text-primary-normal);
57
- --mdc-toggle-border-color: var(--mds-color-theme-outline-primary-disabled);
58
- --mdc-toggle-background-color: var(--mds-color-theme-control-inactive-disabled);
56
+ --mdc-statictoggle-icon-background-color: var(--mds-color-theme-common-text-primary-normal);
57
+ --mdc-statictoggle-border-color: var(--mds-color-theme-outline-primary-disabled);
58
+ --mdc-statictoggle-background-color: var(--mds-color-theme-control-inactive-disabled);
59
59
  }
60
60
 
61
61
  :host([disabled]),
62
62
  :host([soft-disabled]) {
63
- --mdc-toggle-icon-color: var(--mds-color-theme-common-inverted-text-primary-disabled);
64
- --mdc-toggle-icon-background-color: var(--mds-color-theme-common-text-primary-disabled);
65
- --mdc-toggle-border-color: var(--mds-color-theme-outline-primary-disabled);
66
- --mdc-toggle-background-color: var(--mds-color-theme-control-inactive-disabled);
63
+ --mdc-statictoggle-icon-color: var(--mds-color-theme-common-inverted-text-primary-disabled);
64
+ --mdc-statictoggle-icon-background-color: var(--mds-color-theme-common-text-primary-disabled);
65
+ --mdc-statictoggle-border-color: var(--mds-color-theme-outline-primary-disabled);
66
+ --mdc-statictoggle-background-color: var(--mds-color-theme-control-inactive-disabled);
67
67
  cursor: default;
68
68
  }
69
69
 
70
70
  :host([checked][disabled]),
71
71
  :host([checked][soft-disabled]) {
72
- --mdc-toggle-icon-color: var(--mds-color-theme-common-inverted-text-primary-disabled);
73
- --mdc-toggle-icon-background-color: var(--mds-color-theme-common-text-primary-disabled);
74
- --mdc-toggle-border-color: transparent;
75
- --mdc-toggle-background-color: var(--mds-color-theme-control-active-disabled);
72
+ --mdc-statictoggle-icon-color: var(--mds-color-theme-common-inverted-text-primary-disabled);
73
+ --mdc-statictoggle-icon-background-color: var(--mds-color-theme-common-text-primary-disabled);
74
+ --mdc-statictoggle-border-color: transparent;
75
+ --mdc-statictoggle-background-color: var(--mds-color-theme-control-active-disabled);
76
76
  }
77
77
 
78
78
  /* High Contrast Mode */
79
79
  @media (forced-colors: active) {
80
80
  :host::part(toggle-icon) {
81
- --mdc-toggle-icon-color: CanvasText;
82
- border: 1px solid var(--mdc-toggle-border-color);
81
+ --mdc-statictoggle-icon-color: CanvasText;
82
+ border: 1px solid var(--mdc-statictoggle-border-color);
83
83
  }
84
84
 
85
85
  :host([checked]) {
86
- --mdc-toggle-icon-color: SelectedItemText;
87
- --mdc-toggle-border-color: SelectedItem;
88
- --mdc-toggle-background-color: SelectedItem;
86
+ --mdc-statictoggle-icon-color: SelectedItemText;
87
+ --mdc-statictoggle-border-color: SelectedItem;
88
+ --mdc-statictoggle-background-color: SelectedItem;
89
89
  }
90
90
 
91
91
  :host([disabled])::part(toggle-icon),
92
92
  :host([soft-disabled])::part(toggle-icon) {
93
- --mdc-toggle-icon-color: GrayText;
93
+ --mdc-statictoggle-icon-color: GrayText;
94
94
  border: 1px solid GrayText;
95
95
  }
96
96
  }
package/dist/components/toggle/toggle.component.d.ts CHANGED
@@ -4,14 +4,25 @@ import FormfieldWrapper from '../formfieldwrapper';
4
4
  import type { ToggleSize } from './toggle.types';
5
5
  declare const Toggle_base: import("../../utils/mixins/index.types").Constructor<import("../../models").Component & import("../../utils/mixins/AutoFocusOnMountMixin").AutoFocusOnMountMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/FormInternalsMixin").FormInternalsMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DataAriaLabelMixin").DataAriaLabelMixinInterface> & typeof FormfieldWrapper;
6
6
  /**
7
- * Toggle Component is an interactive control used to switch between two mutually exclusive options,
8
- * such as On/Off, Active/Inactive. These are commonly used in settings panels, forms, and preference selections
7
+ * The Toggle component is an interactive control used to switch between two mutually exclusive states,
8
+ * such as On/Off or Active/Inactive. It is commonly used in settings panels, forms, and preference selections
9
9
  * where users need to enable or disable a feature.
10
- * It contains an optional label and an optional helper text.
11
10
  *
12
- * To create a group of toggles, use the FormFieldGroup component.
11
+ * To create a group of toggles, use the `mdc-formfieldgroup` component.
13
12
  *
14
- * Note: It internally renders a checkbox styled as a toggle switch.
13
+ * **Note:** This component internally renders a native checkbox input element styled as a toggle switch.
14
+ *
15
+ * ## When to use
16
+ * Use toggles for binary choices where the change takes effect immediately, such as enabling/disabling settings or features.
17
+ *
18
+ * ## Accessibility
19
+ * - Provide clear labels that describe what the toggle controls
20
+ * - Use `data-aria-label` when a visual label is not present
21
+ * - Keyboard navigation: Space to toggle, Tab to navigate, Enter to submit form
22
+ *
23
+ * ## Styling
24
+ * Use the `static-toggle` part to apply custom styles to the toggle switch visual element.
25
+ * This part exposes the underlying [StaticToggle](?path=/docs/components-decorator-statictoggle--docs) component for advanced styling.
15
26
  *
16
27
  * @dependency mdc-button
17
28
  * @dependency mdc-icon
@@ -24,14 +35,6 @@ declare const Toggle_base: import("../../utils/mixins/index.types").Constructor<
24
35
  * @event change - (React: onChange) Event that gets dispatched when the toggle state changes.
25
36
  * @event focus - (React: onFocus) Event that gets dispatched when the toggle receives focus.
26
37
  *
27
- * @cssproperty --mdc-toggle-width - The width of the toggle
28
- * @cssproperty --mdc-toggle-height - The height of the toggle
29
- * @cssproperty --mdc-toggle-border-radius - The border radius of the toggle
30
- * @cssproperty --mdc-toggle-border-color - The border color of the toggle
31
- * @cssproperty --mdc-toggle-background-color - The background color of the toggle
32
- * @cssproperty --mdc-toggle-icon-color - The icon color of the toggle
33
- * @cssproperty --mdc-toggle-icon-background-color - The icon background color of the toggle
34
- *
35
38
  * @csspart label - The label element.
36
39
  * @csspart label-text - The container for the label and required indicator elements.
37
40
  * @csspart required-indicator - The required indicator element that is displayed next to the label when the `required` property is set to true.
@@ -40,19 +43,21 @@ declare const Toggle_base: import("../../utils/mixins/index.types").Constructor<
40
43
  * @csspart help-text - The helper/validation text element.
41
44
  * @csspart helper-icon - The helper/validation icon element that is displayed next to the helper/validation text.
42
45
  * @csspart help-text-container - The container for the helper/validation icon and text elements.
43
- * @csspart static-toggle - The static-toggle element that wraps the toggle input.
44
- * @csspart toggle-input - The native checkbox input element styled as a toggle switch.
46
+ * @csspart static-toggle - The statictoggle that provides the visual toggle switch appearance.
47
+ * @csspart toggle-input - The native checkbox input element that provides the interactive functionality.
45
48
  */
46
49
  declare class Toggle extends Toggle_base implements AssociatedFormControl {
47
50
  /**
48
- * Determines whether the toggle is active or inactive.
51
+ * Controls the state of the toggle switch.
52
+ * When true, the toggle is in the "on" or "active" state.
53
+ * When false, the toggle is in the "off" or "inactive" state.
49
54
  * @default false
50
55
  */
51
56
  checked: boolean;
52
57
  /**
53
- * Determines toggle size in rem (height is specified here).
54
- * - **Default**: 1.5
55
- * - **Compact**: 1
58
+ * Specifies the size of the toggle component.
59
+ * - **default**: Standard size with 1.5rem height - suitable for most use cases
60
+ * - **compact**: Smaller size with 1rem height - ideal for space-constrained layouts
56
61
  * @default default
57
62
  */
58
63
  size: ToggleSize;
@@ -70,28 +75,33 @@ declare class Toggle extends Toggle_base implements AssociatedFormControl {
70
75
  * If the checkbox is not checked and the required property is set, then the checkbox is invalid.
71
76
  * If the validationMessage is set, it will be used as the custom validity message.
72
77
  * If the validationMessage is not set, it will clear the custom validity message.
78
+ * @internal
73
79
  */
74
80
  private manageRequired;
75
81
  /**
76
82
  * Updates the form value to reflect the current state of the toggle.
77
83
  * If toggle is switched on, the value is set to either the user-provided value or 'isActive' if no value is provided.
78
84
  * If toggle is switched off, the value is set to null.
85
+ * @internal
79
86
  */
80
87
  private setFormValue;
81
88
  /**
82
89
  * Toggles the state of the toggle element.
83
90
  * If the element is not disabled, soft-disabled, or readonly, then the checked property is toggled.
91
+ * @internal
84
92
  */
85
93
  private toggleState;
86
94
  /**
87
95
  * Handles the keydown event on the toggle element.
88
96
  * When the user presses Enter, the form is submitted.
89
97
  * @param event - The keyboard event.
98
+ * @internal
90
99
  */
91
100
  private handleKeyDown;
92
101
  /**
93
102
  * Toggles the state of the toggle element.
94
103
  * and dispatch the new change event.
104
+ * @internal
95
105
  */
96
106
  private handleChange;
97
107
  /**
@@ -100,6 +110,7 @@ declare class Toggle extends Toggle_base implements AssociatedFormControl {
100
110
  * it defaults to the value specified in DEFAULTS.SIZE.
101
111
  *
102
112
  * @param size - The size to set.
113
+ * @internal
103
114
  */
104
115
  private setToggleSize;
105
116
  update(changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>): void;
package/dist/components/toggle/toggle.component.js CHANGED
@@ -20,14 +20,25 @@ import { DEFAULTS as FORMFIELD_DEFAULTS } from '../formfieldwrapper/formfieldwra
20
20
  import { DEFAULTS, TOGGLE_SIZE } from './toggle.constants';
21
21
  import styles from './toggle.styles';
22
22
  /**
23
- * Toggle Component is an interactive control used to switch between two mutually exclusive options,
24
- * such as On/Off, Active/Inactive. These are commonly used in settings panels, forms, and preference selections
23
+ * The Toggle component is an interactive control used to switch between two mutually exclusive states,
24
+ * such as On/Off or Active/Inactive. It is commonly used in settings panels, forms, and preference selections
25
25
  * where users need to enable or disable a feature.
26
- * It contains an optional label and an optional helper text.
27
26
  *
28
- * To create a group of toggles, use the FormFieldGroup component.
27
+ * To create a group of toggles, use the `mdc-formfieldgroup` component.
29
28
  *
30
- * Note: It internally renders a checkbox styled as a toggle switch.
29
+ * **Note:** This component internally renders a native checkbox input element styled as a toggle switch.
30
+ *
31
+ * ## When to use
32
+ * Use toggles for binary choices where the change takes effect immediately, such as enabling/disabling settings or features.
33
+ *
34
+ * ## Accessibility
35
+ * - Provide clear labels that describe what the toggle controls
36
+ * - Use `data-aria-label` when a visual label is not present
37
+ * - Keyboard navigation: Space to toggle, Tab to navigate, Enter to submit form
38
+ *
39
+ * ## Styling
40
+ * Use the `static-toggle` part to apply custom styles to the toggle switch visual element.
41
+ * This part exposes the underlying [StaticToggle](?path=/docs/components-decorator-statictoggle--docs) component for advanced styling.
31
42
  *
32
43
  * @dependency mdc-button
33
44
  * @dependency mdc-icon
@@ -40,14 +51,6 @@ import styles from './toggle.styles';
40
51
  * @event change - (React: onChange) Event that gets dispatched when the toggle state changes.
41
52
  * @event focus - (React: onFocus) Event that gets dispatched when the toggle receives focus.
42
53
  *
43
- * @cssproperty --mdc-toggle-width - The width of the toggle
44
- * @cssproperty --mdc-toggle-height - The height of the toggle
45
- * @cssproperty --mdc-toggle-border-radius - The border radius of the toggle
46
- * @cssproperty --mdc-toggle-border-color - The border color of the toggle
47
- * @cssproperty --mdc-toggle-background-color - The background color of the toggle
48
- * @cssproperty --mdc-toggle-icon-color - The icon color of the toggle
49
- * @cssproperty --mdc-toggle-icon-background-color - The icon background color of the toggle
50
- *
51
54
  * @csspart label - The label element.
52
55
  * @csspart label-text - The container for the label and required indicator elements.
53
56
  * @csspart required-indicator - The required indicator element that is displayed next to the label when the `required` property is set to true.
@@ -56,21 +59,23 @@ import styles from './toggle.styles';
56
59
  * @csspart help-text - The helper/validation text element.
57
60
  * @csspart helper-icon - The helper/validation icon element that is displayed next to the helper/validation text.
58
61
  * @csspart help-text-container - The container for the helper/validation icon and text elements.
59
- * @csspart static-toggle - The static-toggle element that wraps the toggle input.
60
- * @csspart toggle-input - The native checkbox input element styled as a toggle switch.
62
+ * @csspart static-toggle - The statictoggle that provides the visual toggle switch appearance.
63
+ * @csspart toggle-input - The native checkbox input element that provides the interactive functionality.
61
64
  */
62
65
  class Toggle extends AutoFocusOnMountMixin(FormInternalsMixin(DataAriaLabelMixin(FormfieldWrapper))) {
63
66
  constructor() {
64
67
  super(...arguments);
65
68
  /**
66
- * Determines whether the toggle is active or inactive.
69
+ * Controls the state of the toggle switch.
70
+ * When true, the toggle is in the "on" or "active" state.
71
+ * When false, the toggle is in the "off" or "inactive" state.
67
72
  * @default false
68
73
  */
69
74
  this.checked = false;
70
75
  /**
71
- * Determines toggle size in rem (height is specified here).
72
- * - **Default**: 1.5
73
- * - **Compact**: 1
76
+ * Specifies the size of the toggle component.
77
+ * - **default**: Standard size with 1.5rem height - suitable for most use cases
78
+ * - **compact**: Smaller size with 1rem height - ideal for space-constrained layouts
74
79
  * @default default
75
80
  */
76
81
  this.size = DEFAULTS.SIZE;
@@ -107,6 +112,7 @@ class Toggle extends AutoFocusOnMountMixin(FormInternalsMixin(DataAriaLabelMixin
107
112
  * If the checkbox is not checked and the required property is set, then the checkbox is invalid.
108
113
  * If the validationMessage is set, it will be used as the custom validity message.
109
114
  * If the validationMessage is not set, it will clear the custom validity message.
115
+ * @internal
110
116
  */
111
117
  manageRequired() {
112
118
  if (!this.checked && this.required) {
@@ -126,6 +132,7 @@ class Toggle extends AutoFocusOnMountMixin(FormInternalsMixin(DataAriaLabelMixin
126
132
  * Updates the form value to reflect the current state of the toggle.
127
133
  * If toggle is switched on, the value is set to either the user-provided value or 'isActive' if no value is provided.
128
134
  * If toggle is switched off, the value is set to null.
135
+ * @internal
129
136
  */
130
137
  setFormValue() {
131
138
  let actualValue = null;
@@ -141,6 +148,7 @@ class Toggle extends AutoFocusOnMountMixin(FormInternalsMixin(DataAriaLabelMixin
141
148
  /**
142
149
  * Toggles the state of the toggle element.
143
150
  * If the element is not disabled, soft-disabled, or readonly, then the checked property is toggled.
151
+ * @internal
144
152
  */
145
153
  toggleState() {
146
154
  if (!this.disabled && !this.softDisabled && !this.readonly) {
@@ -151,6 +159,7 @@ class Toggle extends AutoFocusOnMountMixin(FormInternalsMixin(DataAriaLabelMixin
151
159
  * Handles the keydown event on the toggle element.
152
160
  * When the user presses Enter, the form is submitted.
153
161
  * @param event - The keyboard event.
162
+ * @internal
154
163
  */
155
164
  handleKeyDown(event) {
156
165
  var _a;
@@ -164,6 +173,7 @@ class Toggle extends AutoFocusOnMountMixin(FormInternalsMixin(DataAriaLabelMixin
164
173
  /**
165
174
  * Toggles the state of the toggle element.
166
175
  * and dispatch the new change event.
176
+ * @internal
167
177
  */
168
178
  handleChange(event) {
169
179
  this.toggleState();
@@ -176,6 +186,7 @@ class Toggle extends AutoFocusOnMountMixin(FormInternalsMixin(DataAriaLabelMixin
176
186
  * it defaults to the value specified in DEFAULTS.SIZE.
177
187
  *
178
188
  * @param size - The size to set.
189
+ * @internal
179
190
  */
180
191
  setToggleSize(size) {
181
192
  this.setAttribute('size', Object.values(TOGGLE_SIZE).includes(size) ? size : DEFAULTS.SIZE);
package/dist/components/toggle/toggle.styles.js CHANGED
@@ -3,6 +3,12 @@ import { hostFitContentStyles, hostFocusRingStyles } from '../../utils/styles';
3
3
  const styles = [
4
4
  hostFitContentStyles,
5
5
  css `
6
+ :host {
7
+ --mdc-label-font-size: var(--mds-font-apps-body-midsize-regular-font-size);
8
+ --mdc-label-font-weight: var(--mds-font-apps-body-midsize-regular-font-weight);
9
+ --mdc-label-line-height: var(--mds-font-apps-body-midsize-regular-line-height);
10
+ }
11
+
6
12
  /* Grid layout for labeled toggles */
7
13
  :host([label]),
8
14
  :host([help-text]) {
@@ -31,16 +37,13 @@ const styles = [
31
37
  opacity: 0.1%;
32
38
  overflow: visible;
33
39
  z-index: 1;
34
- width: var(--mdc-toggle-width);
35
- height: var(--mdc-toggle-height);
40
+ width: var(--mdc-statictoggle-width);
41
+ height: var(--mdc-statictoggle-height);
36
42
  }
37
43
 
38
44
  :host::part(label) {
39
45
  word-break: break-word;
40
46
  white-space: normal;
41
- --mdc-label-font-size: var(--mds-font-apps-body-midsize-regular-font-size);
42
- --mdc-label-font-weight: var(--mds-font-apps-body-midsize-regular-font-weight);
43
- --mdc-label-line-height: var(--mds-font-apps-body-midsize-regular-line-height);
44
47
  }
45
48
 
46
49
  /* Default interactive states */
@@ -50,19 +53,19 @@ const styles = [
50
53
  }
51
54
 
52
55
  :host(:hover)::part(static-toggle) {
53
- --mdc-toggle-background-color: var(--mds-color-theme-control-inactive-hover);
56
+ --mdc-statictoggle-background-color: var(--mds-color-theme-control-inactive-hover);
54
57
  }
55
58
 
56
59
  :host(:active)::part(static-toggle) {
57
- --mdc-toggle-background-color: var(--mds-color-theme-control-inactive-pressed);
60
+ --mdc-statictoggle-background-color: var(--mds-color-theme-control-inactive-pressed);
58
61
  }
59
62
 
60
63
  :host([checked]:hover)::part(static-toggle) {
61
- --mdc-toggle-background-color: var(--mds-color-theme-control-active-hover);
64
+ --mdc-statictoggle-background-color: var(--mds-color-theme-control-active-hover);
62
65
  }
63
66
 
64
67
  :host([checked]:active)::part(static-toggle) {
65
- --mdc-toggle-background-color: var(--mds-color-theme-control-active-pressed);
68
+ --mdc-statictoggle-background-color: var(--mds-color-theme-control-active-pressed);
66
69
  }
67
70
 
68
71
  /* Readonly state - disables pointer events */
package/dist/components/toggle/toggle.types.d.ts CHANGED
@@ -2,8 +2,9 @@ import type { OverrideEventTarget, TypedCustomEvent, ValueOf } from '../../utils
2
2
  import type Toggle from './toggle.component';
3
3
  import { TOGGLE_SIZE } from './toggle.constants';
4
4
  type ToggleSize = ValueOf<typeof TOGGLE_SIZE>;
5
+ type ToggleOnChangeEvent = TypedCustomEvent<Toggle>;
5
6
  interface Events {
6
- onChangeEvent: TypedCustomEvent<Toggle>;
7
+ onChangeEvent: ToggleOnChangeEvent;
7
8
  onFocusEvent: OverrideEventTarget<FocusEvent, Toggle>;
8
9
  }
9
- export type { ToggleSize, Events };
10
+ export type { ToggleSize, Events, ToggleOnChangeEvent };