@globalpayments/vega 2.88.0 → 2.89.0

package/dist/collection/components/vega-checkbox/vega-checkbox.js

@@ -5,17 +5,16 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Component, Host, h, Element, Prop, Event, Watch, Method, State } from '@stencil/core';
-import { createEnterKeyHandlerToTriggerClick } from '../../utils/accessibility';
 import { sanitizeVegaComponent } from '../../utils/component';
 import { CheckBoxRequiredRule } from '../../helpers/validator/rules/check-box-required-rule';
 import ChangeManager from '../../helpers/change-manager/change-manager';
-import { CHECKBOX_GROUP_DISABLED_CHANGE, CHECKBOX_VALUE_CHANGE, FORM_ELEMENT_VALUE_CHANGE, } from '../../helpers/change-manager/subject/static-subject/static-subject-title';
+import { CHECKBOX_GROUP_DISABLED_CHANGE, CHECKBOX_USER_INTERACTION, CHECKBOX_VALUE_CHANGE, FORM_ELEMENT_VALUE_CHANGE, } from '../../helpers/change-manager/subject/static-subject/static-subject-title';
 import { Observer } from '../../helpers/change-manager/observer/observer';
 import { arrayToClassString, findParent } from '../../utils/ui';
 import { InjectVegaGlobalSlimmer, InjectVegaSlimmer } from 'vega-slimmer/core';
 import { FormFieldControllerSlimmer } from '../../helpers/slimmers/form-field-controller-slimmer';
 import { createEventEmitSlimmer, } from '../../helpers/event-manager/slimmers/event-emit-slimmer';
-import { VegaChange } from '../../helpers/event-manager/event-id/vega-event-id';
+import { VegaChange, VegaUserChange } from '../../helpers/event-manager/event-id/vega-event-id';
 import { VegaCheckboxShowErrorController } from './slimmers/controllers/vega-checkbox-show-error-controller';
 import { VegaComponentUsageRuntimeMetricsSlimmer } from '../../helpers/slimmers/component-usage-runtime-metrics';
 import { ChildNodesEventPreventSlimmer } from '../../helpers/event-manager/slimmers/child-nodes-event-prevent-slimmer';
@@ -48,12 +47,15 @@ export class VegaCheckbox {
       touchableAreaGetter: () => [this.inputRef],
     });
     this.changeEventEmitter = createEventEmitSlimmer(VegaCheckbox, VegaChange);
-    this.dropdownEventPrevent = new ChildNodesEventPreventSlimmer([VegaChange], () => this.host, {
+    this.userChangeEventEmitter = createEventEmitSlimmer(VegaCheckbox, VegaUserChange);
+    this.dropdownEventPrevent = new ChildNodesEventPreventSlimmer([VegaChange, VegaUserChange], () => this.host, {
       customPreventHandle: (e) => {
         e.stopPropagation();
       },
     });
     this.vegaComponentUsageRuntimeMetricsSlimmer = new VegaComponentUsageRuntimeMetricsSlimmer();
+    this.labelClickPending = false;
+    this.isUserInteraction = false;
     /**
      * Indicates whether the parent checkbox group is disabled.
      */
@@ -146,7 +148,62 @@ export class VegaCheckbox {
       if (this.indeterminate) {
         this.indeterminate = false;
       }
+      this.isUserInteraction = true;
       this.checked = e.currentTarget.checked;
+      // Defensive: Stencil watchers run synchronously on the setter, so by
+      // the time the line above returns, watchCheckedChange has already run
+      // (or been skipped under a future same-value guard, e.g. VD-8009).
+      // Queue an unconditional clear as a safety net so a skipped watcher
+      // can never leak the flag into the next prop-driven update.
+      this.isUserInteraction = false;
+    };
+    // Toggle checked directly on Enter to avoid synthetic click bubbling through
+    // the <label>, which would fire vegaChange twice via a second onChange.
+    this.onInputKeyDown = (e) => {
+      if (e.key !== 'Enter')
+        return;
+      e.preventDefault();
+      if (this.isDisabled())
+        return;
+      if (this.indeterminate) {
+        this.indeterminate = false;
+      }
+      this.isUserInteraction = true;
+      this.checked = !this.checked;
+      this.isUserInteraction = false;
+    };
+    /**
+     * Suppresses the duplicate `click` event that bubbles to the host when the
+     *    browser performs the label's default activation behavior. Clicking the
+     *    label area dispatches one click on the label (which bubbles to the
+     *    host), and the browser then synthesizes a second click on the wrapped
+     *    `<input>`, which also bubbles through the label to the host — causing
+     *    the consumer's `onClick` to fire twice.
+     *
+     * We tag the original label-area click with `labelClickPending = true` and,
+     *    when the synthetic input click bubbles back through the label, call
+     *    `stopPropagation()` to prevent the duplicate from leaving the host.
+     *    The input still toggles natively (no `preventDefault`), so `change`
+     *    fires once and `vegaChange` is emitted exactly once via the normal
+     *    `@Watch('checked')` path. This avoids the spurious same-value emission
+     *    that an optimistic local toggle would cause in React controlled
+     *    components, where the parent re-renders the same `checked` value.
+     */
+    this.onLabelClick = (e) => {
+      if (e.target === this.inputRef) {
+        if (this.labelClickPending) {
+          e.stopPropagation();
+          this.labelClickPending = false;
+        }
+        return;
+      }
+      this.labelClickPending = true;
+      // Defensive reset for cases where no synthetic input click follows
+      // (e.g. disabled input, or the click landing outside the label's
+      // associated form control).
+      setTimeout(() => {
+        this.labelClickPending = false;
+      }, 0);
     };
     this.onSelectedIconClick = (e) => {
       e.stopPropagation();
@@ -159,8 +216,18 @@ export class VegaCheckbox {
     this.checked = this.identifier !== '' ? newValue === this.identifier : newValue === true;
   }
   watchCheckedChange() {
+    // Snapshot + unconditional clear so the user-interaction flag never
+    // leaks into a later prop-driven update. Stencil's prop setter only
+    // invokes @Watch when the value actually changed, so a click that
+    // does not flip `checked` would otherwise leave the flag set.
+    const wasUserInteraction = this.isUserInteraction;
+    this.isUserInteraction = false;
     this.initValue();
     this.changeEventEmitter.emit(this.value);
+    if (wasUserInteraction) {
+      this.userChangeEventEmitter.emit(this.value);
+      ChangeManager.notify(CHECKBOX_USER_INTERACTION, { host: this.host, detail: this.value });
+    }
     ChangeManager.notify(CHECKBOX_VALUE_CHANGE, { host: this.host, detail: this.value });
     ChangeManager.notify(FORM_ELEMENT_VALUE_CHANGE, {
       host: this.host,
@@ -181,6 +248,21 @@ export class VegaCheckbox {
     this.initValue();
     this.initAndRegisterGroupDisabledObserver();
   }
+  /**
+   * Prevents redundant updates when the checked prop is set
+   *    to the same value (e.g., from parent re-renders in React).
+   *
+   * @param {unknown} newValue - The new prop value.
+   * @param {unknown} oldValue - The old prop value.
+   * @param {string} name - The property name.
+   * @returns {boolean} Return false to skip the current update flow.
+   */
+  componentShouldUpdate(newValue, oldValue, name) {
+    if (name === 'checked' && newValue === oldValue) {
+      return false;
+    }
+    return true;
+  }
   componentDidRender() {
     if (this.host.innerHTML.trim() === '') {
       this.labelElement.classList.add('vega-hidden');
@@ -211,8 +293,8 @@ export class VegaCheckbox {
           'vega-checkbox-container',
           this.showError && 'error',
           this.size && `size-${this.size}`,
-        ]), ref: (e) => (this.inputContainerRef = e) },
-        h("input", { ref: (e) => (this.inputRef = e), type: "checkbox", checked: this.checked, value: this.identifier, onChange: this.onCheckBoxChange, "aria-checked": this.indeterminate ? 'mixed' : undefined, disabled: this.isDisabled(), tabIndex: 0, onKeyDown: createEnterKeyHandlerToTriggerClick() }),
+        ]), ref: (e) => (this.inputContainerRef = e), onClick: this.onLabelClick },
+        h("input", { ref: (e) => (this.inputRef = e), type: "checkbox", checked: this.checked, value: this.identifier, onChange: this.onCheckBoxChange, "aria-label": this.identifier || 'No label defined', "aria-checked": this.indeterminate ? 'mixed' : undefined, disabled: this.isDisabled(), tabIndex: 0, onKeyDown: this.onInputKeyDown }),
         h("span", { class: "vega-checkbox-icon", onClick: this.onSelectedIconClick, tabIndex: -1, "aria-hidden": "true" }, this.renderIconDom()),
         h("div", { class: "vega-checkbox-label-container", ref: (el) => (this.labelElement = el) },
           this.renderLabelDom(),
@@ -488,6 +570,63 @@ export class VegaCheckbox {
         "resolved": "boolean | string",
         "references": {}
       }
+    }, {
+      "method": "vegaUserChange",
+      "name": "vegaUserChange",
+      "bubbles": true,
+      "cancelable": true,
+      "composed": true,
+      "docs": {
+        "tags": [{
+            "name": "remarks",
+            "text": "Calling `event.preventDefault()` is a no-op \u2014 it does not roll\nback `checked`/`value` nor suppress the paired `vegaChange` event.\n`cancelable: true` is retained only for parity with `vegaChange`."
+          }, {
+            "name": "see",
+            "text": "{module :vega-checkbox-user-change}"
+          }, {
+            "name": "see",
+            "text": "{module :vega-checkbox-user-change-keyboard}"
+          }, {
+            "name": "see",
+            "text": "{module :vega-checkbox-user-change-keyboard-enter}"
+          }, {
+            "name": "see",
+            "text": "{module :vega-checkbox-user-change-programmatic}"
+          }, {
+            "name": "see",
+            "text": "{module :vega-checkbox-user-change-containment}"
+          }, {
+            "name": "vegaVersion",
+            "text": "2.89.0"
+          }],
+        "text": "An event emitter notifying changes in the value of the checkbox\n   triggered exclusively by user interaction (mouse click or keyboard activation).\n\nUnlike `vegaChange`, this event does NOT fire when the `checked` or `value`\n   prop is reassigned programmatically. Use this event when you want to react\n   only to real user input (e.g., analytics, derived \"select all\" state)."
+      },
+      "complexType": {
+        "original": "string | boolean",
+        "resolved": "boolean | string",
+        "references": {}
+      }
+    }, {
+      "method": "userChange",
+      "name": "userChange",
+      "bubbles": true,
+      "cancelable": true,
+      "composed": true,
+      "docs": {
+        "tags": [{
+            "name": "eventSemantics",
+            "text": "namespace:native"
+          }, {
+            "name": "vegaVersion",
+            "text": "2.89.0"
+          }],
+        "text": "An event emitter notifying changes in the value of the checkbox\n   triggered exclusively by user interaction (mouse click or keyboard activation)."
+      },
+      "complexType": {
+        "original": "string | boolean",
+        "resolved": "boolean | string",
+        "references": {}
+      }
     }, {
       "method": "change",
       "name": "change",
@@ -558,6 +697,9 @@ __decorate([
 __decorate([
   InjectVegaSlimmer()
 ], VegaCheckbox.prototype, "changeEventEmitter", void 0);
+__decorate([
+  InjectVegaSlimmer()
+], VegaCheckbox.prototype, "userChangeEventEmitter", void 0);
 __decorate([
   InjectVegaSlimmer()
 ], VegaCheckbox.prototype, "dropdownEventPrevent", void 0);

package/dist/collection/components/vega-chip/vega-chip.css

@@ -2032,6 +2032,7 @@
   max-width: 100%;
   position: relative;
   border-radius: 9999px;
+  vertical-align: middle;
 }
 :host vega-flex {
   border-radius: 9999px;

package/dist/collection/components/vega-chip/vega-chip.js

@@ -183,7 +183,7 @@ export class VegaChip {
   }
   renderText() {
     return (h("span", { class: "vega-chip-text" },
-      h("vega-text", { overflow: "ellipsis", key: this.text }, this.text)));
+      h("vega-text", { overflow: "ellipsis", text: this.text, key: this.text })));
   }
   setCurrentSize() {
     this.currentSize = ResponsiveFormatFacade.formatCustom(this.size);

package/dist/collection/components/vega-color-picker/vega-color-picker.js

@@ -66,6 +66,16 @@ export class VegaColorPicker {
      * @vegaVersion 1.13.0
      */
     this.required = false;
+    /**
+     * Indicates whether the field should be presented as optional.
+     *
+     * This property only takes effect when `required` is `false`.
+     * When `true`, an "optional" label is displayed next to the field label.
+     *
+     * @default false
+     * @vegaVersion 2.89.0
+     */
+    this.optional = false;
     /**
      * Specifies the label or title for the color picker.
      *
@@ -145,7 +155,7 @@ export class VegaColorPicker {
         }))));
     };
     this.renderHintMessage = () => {
-      return h("vega-text", null, this.hint);
+      return h("vega-text", { text: this.hint });
     };
     this.updateValueProp = async (e) => {
       if (!this.disabled) {
@@ -176,7 +186,7 @@ export class VegaColorPicker {
       this.hint && this.renderHintMessage()), this.host);
   }
   renderLabelDom() {
-    return (h("vega-field-label", { "is-field-required": this.required, disabled: this.disabled, label: this.label }));
+    return (h("vega-field-label", { "is-field-required": this.required, optional: this.optional, disabled: this.disabled, label: this.label }));
   }
   getValidColumns() {
     const flooredColumns = Math.floor(this.columns);
@@ -299,6 +309,30 @@ export class VegaColorPicker {
       "reflect": true,
       "defaultValue": "false"
     },
+    "optional": {
+      "type": "boolean",
+      "mutable": false,
+      "complexType": {
+        "original": "boolean",
+        "resolved": "boolean",
+        "references": {}
+      },
+      "required": false,
+      "optional": false,
+      "docs": {
+        "tags": [{
+            "name": "default",
+            "text": "false"
+          }, {
+            "name": "vegaVersion",
+            "text": "2.89.0"
+          }],
+        "text": "Indicates whether the field should be presented as optional.\n\nThis property only takes effect when `required` is `false`.\nWhen `true`, an \"optional\" label is displayed next to the field label."
+      },
+      "attribute": "optional",
+      "reflect": true,
+      "defaultValue": "false"
+    },
     "label": {
       "type": "string",
       "mutable": false,

package/dist/collection/components/vega-combo-box/slimmers/renderers/vega-combo-box-dropdown-renderer.js

@@ -11,6 +11,7 @@ import { DomNodeSubjectObserverFactory } from '../../../../helpers/change-manage
 import { VegaClose, VegaCreate, VegaDropdownClick, VegaDropdownHide, } from '../../../../helpers/event-manager/event-id/vega-event-id';
 import { VegaInternalDropdownTemplateItemsChange } from '../../../../helpers/event-manager/event-id/vega-internal-event-id';
 import { htmlSanitizer, labelSanitizeStrategy } from '../../../../utils/sanitize';
+import { formatAndValidResponsiveToken } from '../../../../utils/design-token';
 export class VegaComboBoxDropdownRenderer extends VegaSlimmer {
   constructor() {
     super(...arguments);
@@ -103,12 +104,20 @@ export class VegaComboBoxDropdownRenderer extends VegaSlimmer {
       this.renderItemsSlot()));
   }
   renderContainer() {
+    const formattedMaxHeight = formatAndValidResponsiveToken(this.containerMaxHeight, 'widthAndHeight');
+    const containerContentStyle = formattedMaxHeight
+      ? {
+        maxHeight: formattedMaxHeight,
+      }
+      : undefined;
     return (h("div", { class: {
         'vega-combo-box-container': true,
         [`vega-combo-box-size-${this.size}`]: true,
-      } },
+      } }, formattedMaxHeight ? (h("div", { class: "vega-combo-box-container-content", style: containerContentStyle },
+      this.renderSelectedContainer(),
+      this.renderInputContainer())) : (h(Fragment, null,
       this.renderSelectedContainer(),
-      this.renderInputContainer()));
+      this.renderInputContainer()))));
   }
   renderItemsSlot() {
     return (this.isTemplateMode && (h("div", { slot: "items", ref: (ref) => {
@@ -160,6 +169,9 @@ __decorate([
 __decorate([
   MapToComponentField()
 ], VegaComboBoxDropdownRenderer.prototype, "size", void 0);
+__decorate([
+  MapToComponentField()
+], VegaComboBoxDropdownRenderer.prototype, "containerMaxHeight", void 0);
 __decorate([
   MapToComponentField()
 ], VegaComboBoxDropdownRenderer.prototype, "vegaDropdownProps", void 0);

package/dist/collection/components/vega-combo-box/vega-combo-box.css

@@ -30,6 +30,18 @@
   border: 1px solid rgba(var(--v-border-input-field-hover, 115, 160, 190, 1));
 }
 
+.vega-combo-box-container-content {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  max-height: 100%;
+  overflow-y: auto;
+  overflow-x: hidden;
+  min-height: 26px;
+}
+
 .vega-combo-box-container:focus-within {
   border: 1px solid rgba(var(--v-border-input-field-focus, 19, 98, 226, 1));
   outline: 2px solid rgba(var(--v-border-color-action, 19, 98, 226, 1));

package/dist/collection/components/vega-combo-box/vega-combo-box.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { Component, Prop, Element, Method, Watch, Event } from '@stencil/core';
+import { Component, Prop, Element, Method, Watch, Event, State } from '@stencil/core';
 import { RequiredFieldRule } from '../../helpers/validator/rules/required-field-rule';
 import { sanitizeVegaComponent } from '../../utils/component';
 import { isArrayOfType, isDropdownSourceItemType } from '../../types/type-guard';
@@ -23,6 +23,7 @@ import { VegaComboBoxRenderer } from './slimmers/renderers/vega-combo-box-render
 import { VegaComboBoxKeyboardController } from './slimmers/controllers/vega-combo-box-keyboard-controller';
 import { VegaComboBoxItemsSlotController } from './slimmers/controllers/vega-combo-box-items-slot-controller';
 import { VegaComboBoxSourceController } from './slimmers/controllers/vega-combo-box-source-controller';
+import { PageResizeObserverSlimmer } from '../../helpers/slimmers/page-resize-observer-slimmer';
 /**
  * @vegaVersion 1.11.0
  */
@@ -35,6 +36,7 @@ export class VegaComboBox {
     this.sourceController = new VegaComboBoxSourceController();
     this.renderer = new VegaComboBoxRenderer();
     this.dropdownRenderer = new VegaComboBoxDropdownRenderer();
+    this.pageResizeSlimmer = new PageResizeObserverSlimmer();
     this.formFieldController = new FormFieldControllerSlimmer({
       propertyRules: [
         {
@@ -182,6 +184,9 @@ export class VegaComboBox {
   watchValidationRules() {
     methodPlaceholder();
   }
+  watchContainerMaxHeight() {
+    methodPlaceholder();
+  }
   /**
    * Invoke this method to close the dropdown menu associated with the combo box.
    *
@@ -478,6 +483,35 @@ export class VegaComboBox {
       "reflect": false,
       "defaultValue": "'medium'"
     },
+    "containerMaxHeight": {
+      "type": "any",
+      "mutable": false,
+      "complexType": {
+        "original": "ResponsiveType<MaxHeightType>",
+        "resolved": "number | string | { S?: MaxHeightType; M?: MaxHeightType; L?: MaxHeightType; XL?: MaxHeightType; default?: MaxHeightType; }",
+        "references": {
+          "ResponsiveType": {
+            "location": "import",
+            "path": "../../types/ui.type"
+          },
+          "MaxHeightType": {
+            "location": "import",
+            "path": "../../types/ui.type"
+          }
+        }
+      },
+      "required": false,
+      "optional": false,
+      "docs": {
+        "tags": [{
+            "name": "vegaVersion",
+            "text": "2.89.0"
+          }],
+        "text": "Specifies the maximum height of the combo box container,\n   including selected chips and input area.\n\nWhen set, vertical scrolling will be enabled once the\n   container content exceeds the configured height.\n\nNote: values smaller than the input minimum height (26px)\n   are floored to keep the input usable. Use\n   `vegaDropdownProps.maxHeight` to control the dropdown\n   menu height independently."
+      },
+      "attribute": "container-max-height",
+      "reflect": true
+    },
     "vegaDropdownProps": {
       "type": "unknown",
       "mutable": false,
@@ -524,6 +558,9 @@ export class VegaComboBox {
       "defaultValue": "true"
     }
   }; }
+  static get states() { return {
+    "currentBreakpoint": {}
+  }; }
   static get events() { return [{
       "method": "vegaChange",
       "name": "vegaChange",
@@ -692,6 +729,9 @@ export class VegaComboBox {
     }, {
       "propName": "validationRules",
       "methodName": "watchValidationRules"
+    }, {
+      "propName": "containerMaxHeight",
+      "methodName": "watchContainerMaxHeight"
     }]; }
 }
 __decorate([
@@ -715,6 +755,9 @@ __decorate([
 __decorate([
   InjectVegaSlimmer()
 ], VegaComboBox.prototype, "dropdownRenderer", void 0);
+__decorate([
+  InjectVegaSlimmer()
+], VegaComboBox.prototype, "pageResizeSlimmer", void 0);
 __decorate([
   InjectVegaSlimmer()
 ], VegaComboBox.prototype, "formFieldController", void 0);

package/dist/collection/components/vega-date-picker/slimmers/renderers/vega-date-picker-renderer.js

@@ -38,7 +38,7 @@ export class VegaDatePickerRenderer extends VegaSlimmer {
           DomNodeSubjectObserverFactory.addUniqueObserverToNode(e, VegaClick, async () => {
             await this.focusInput();
           });
-        }, isFieldRequired: this.required, disabled: this.disabled, label: this.label })));
+        }, isFieldRequired: this.required, disabled: this.disabled, optional: this.optional, label: this.label })));
     };
     /**
      * The below method is e2e-test covered in
@@ -90,6 +90,9 @@ __decorate([
 __decorate([
   MapToComponentField()
 ], VegaDatePickerRenderer.prototype, "required", void 0);
+__decorate([
+  MapToComponentField()
+], VegaDatePickerRenderer.prototype, "optional", void 0);
 __decorate([
   MapToComponentField()
 ], VegaDatePickerRenderer.prototype, "readOnly", void 0);

package/dist/collection/components/vega-date-picker/vega-date-picker.js

@@ -110,6 +110,16 @@ export class VegaDatePicker {
      * @vegaVersion 1.3.0
      */
     this.required = false;
+    /**
+     * Indicates whether the field should be presented as optional.
+     *
+     * This property only takes effect when `required` is `false`.
+     * When `true`, an "optional" label is displayed next to the field label.
+     *
+     * @default false
+     * @vegaVersion 2.89.0
+     */
+    this.optional = false;
     /**
      * Specifies the validation status of the date picker component.
      *
@@ -390,6 +400,30 @@ export class VegaDatePicker {
       "reflect": true,
       "defaultValue": "false"
     },
+    "optional": {
+      "type": "boolean",
+      "mutable": false,
+      "complexType": {
+        "original": "boolean",
+        "resolved": "boolean",
+        "references": {}
+      },
+      "required": false,
+      "optional": false,
+      "docs": {
+        "tags": [{
+            "name": "default",
+            "text": "false"
+          }, {
+            "name": "vegaVersion",
+            "text": "2.89.0"
+          }],
+        "text": "Indicates whether the field should be presented as optional.\n\nThis property only takes effect when `required` is `false`.\nWhen `true`, an \"optional\" label is displayed next to the field label."
+      },
+      "attribute": "optional",
+      "reflect": true,
+      "defaultValue": "false"
+    },
     "isValid": {
       "type": "boolean",
       "mutable": true,

package/dist/collection/components/vega-field-label/slimmers/renderers/vega-field-label-label-announcement-renderer.js

@@ -0,0 +1,69 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { h } from '@stencil/core';
+import { VegaSlimmer, MapToComponentField } from 'vega-slimmer/core';
+/*
+ * Screen-reader-only announcement.
+ *
+ * VoiceOver cannot reliably derive the full field state from the
+ * visible label alone because:
+ *   - "Required" is represented visually by a decorative "*" — AT
+ *     users would hear the raw asterisk character, not a meaningful word.
+ *   - "Disabled" has no visible text marker at all.
+ *
+ * This span provides a single, predictable AT announcement that
+ * concatenates the label text with the plain-English states
+ * (e.g. "Email, Required, Disabled"), ensuring VoiceOver reads
+ * exactly what the user needs to know.
+ *
+ * The visible <label> below is hidden from AT (`aria-hidden="true"`)
+ * to prevent duplicate announcements and to stop VoiceOver from
+ * vocalising the decorative "*" as part of the label text.
+ */
+export class VegaFieldLabelLabelAnnouncementRenderer extends VegaSlimmer {
+  /**
+   * Render a label announcement.
+   *
+   * @returns {Nullable<HTMLElement>}
+   */
+  render() {
+    return this.label && h("span", { class: "aria-announcement" }, this.generateAnnouncement());
+  }
+  /**
+   * Generate a screen-reader-friendly announcement string that concatenates the label text with the field's required/optional and disabled states.
+   *
+   * @returns {string} The generated announcement string.
+   */
+  generateAnnouncement() {
+    let announcement = this.label;
+    if (this.isFieldRequired) {
+      announcement += `, ${this.translationSlimmer.t('Required')}`;
+    }
+    else if (this.optional) {
+      announcement += `, ${this.translationSlimmer.t('Optional')}`;
+    }
+    if (this.disabled) {
+      announcement += `, ${this.translationSlimmer.t('Disabled')}`;
+    }
+    return announcement;
+  }
+}
+__decorate([
+  MapToComponentField()
+], VegaFieldLabelLabelAnnouncementRenderer.prototype, "label", void 0);
+__decorate([
+  MapToComponentField()
+], VegaFieldLabelLabelAnnouncementRenderer.prototype, "isFieldRequired", void 0);
+__decorate([
+  MapToComponentField()
+], VegaFieldLabelLabelAnnouncementRenderer.prototype, "optional", void 0);
+__decorate([
+  MapToComponentField()
+], VegaFieldLabelLabelAnnouncementRenderer.prototype, "disabled", void 0);
+__decorate([
+  MapToComponentField()
+], VegaFieldLabelLabelAnnouncementRenderer.prototype, "translationSlimmer", void 0);

package/dist/collection/components/vega-field-label/vega-field-label.css

@@ -106,4 +106,16 @@ label:first-of-type {
     line-height: 22px;
     letter-spacing: 0px;
   }
+}
+
+.aria-announcement {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
 }

package/dist/collection/components/vega-field-label/vega-field-label.js

@@ -12,6 +12,7 @@ import { VegaClick, VegaLabelButtonClick } from '../../helpers/event-manager/eve
 import { VegaComponentUsageRuntimeMetricsSlimmer } from '../../helpers/slimmers/component-usage-runtime-metrics';
 import { VegaFieldLabelSuffixElementRenderer } from './slimmers/renderers/vega-field-label-suffix-element-renderer';
 import { TranslationSlimmer } from '../../helpers/slimmers/translation/translation-slimmer';
+import { VegaFieldLabelLabelAnnouncementRenderer } from './slimmers/renderers/vega-field-label-label-announcement-renderer';
 /**
  * @vegaVersion 1.10.0
  */
@@ -26,6 +27,7 @@ export class VegaFieldLabel {
     this.suffixButtonClickEventEmitter = createEventEmitSlimmer(VegaFieldLabel, VegaLabelButtonClick);
     this.vegaComponentUsageRuntimeMetricsSlimmer = new VegaComponentUsageRuntimeMetricsSlimmer();
     this.suffixElementRenderer = new VegaFieldLabelSuffixElementRenderer();
+    this.labelAnnouncementRenderer = new VegaFieldLabelLabelAnnouncementRenderer();
     this.translationSlimmer = new TranslationSlimmer();
     /**
      * @deprecated Please use `suffixButtonConfig` instead
@@ -101,9 +103,13 @@ export class VegaFieldLabel {
         hidden: this.label === '',
         disabled: this.disabled,
       }, onClick: this.handleClick },
-      h("label", null,
+      this.labelAnnouncementRenderer.render(),
+      h("label", { "aria-hidden": "true" },
         h("span", { class: "vega-field-label" }, this.label),
-        !this.isFieldRequired && this.optional && (h("span", { class: "optional" }, this.translationSlimmer.t('(Optional)'))),
+        !this.isFieldRequired && this.optional && (h("span", { class: "optional" },
+          "(",
+          this.translationSlimmer.t('Optional'),
+          ")")),
         h("span", { class: {
             'vega-field-label-required': true,
             'hidden': !this.isFieldRequired,
@@ -337,6 +343,9 @@ __decorate([
 __decorate([
   InjectVegaSlimmer()
 ], VegaFieldLabel.prototype, "suffixElementRenderer", void 0);
+__decorate([
+  InjectVegaSlimmer()
+], VegaFieldLabel.prototype, "labelAnnouncementRenderer", void 0);
 __decorate([
   InjectVegaSlimmer()
 ], VegaFieldLabel.prototype, "translationSlimmer", void 0);