@vaadin/field-highlighter 25.3.0-alpha10 → 25.3.0-alpha12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/field-highlighter",
-  "version": "25.3.0-alpha10",
+  "version": "25.3.0-alpha12",
   "publishConfig": {
     "access": "public"
   },
@@ -32,33 +32,33 @@
     "field"
   ],
   "dependencies": {
-    "@vaadin/a11y-base": "25.3.0-alpha10",
-    "@vaadin/component-base": "25.3.0-alpha10",
-    "@vaadin/overlay": "25.3.0-alpha10",
-    "@vaadin/popover": "25.3.0-alpha10",
-    "@vaadin/tooltip": "25.3.0-alpha10",
-    "@vaadin/vaadin-themable-mixin": "25.3.0-alpha10",
+    "@vaadin/a11y-base": "25.3.0-alpha12",
+    "@vaadin/component-base": "25.3.0-alpha12",
+    "@vaadin/overlay": "25.3.0-alpha12",
+    "@vaadin/popover": "25.3.0-alpha12",
+    "@vaadin/tooltip": "25.3.0-alpha12",
+    "@vaadin/vaadin-themable-mixin": "25.3.0-alpha12",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/aura": "25.3.0-alpha10",
-    "@vaadin/chai-plugins": "25.3.0-alpha10",
-    "@vaadin/checkbox": "25.3.0-alpha10",
-    "@vaadin/checkbox-group": "25.3.0-alpha10",
-    "@vaadin/custom-field": "25.3.0-alpha10",
-    "@vaadin/date-picker": "25.3.0-alpha10",
-    "@vaadin/date-time-picker": "25.3.0-alpha10",
-    "@vaadin/item": "25.3.0-alpha10",
-    "@vaadin/list-box": "25.3.0-alpha10",
-    "@vaadin/radio-group": "25.3.0-alpha10",
-    "@vaadin/select": "25.3.0-alpha10",
-    "@vaadin/test-runner-commands": "25.3.0-alpha10",
+    "@vaadin/aura": "25.3.0-alpha12",
+    "@vaadin/chai-plugins": "25.3.0-alpha12",
+    "@vaadin/checkbox": "25.3.0-alpha12",
+    "@vaadin/checkbox-group": "25.3.0-alpha12",
+    "@vaadin/custom-field": "25.3.0-alpha12",
+    "@vaadin/date-picker": "25.3.0-alpha12",
+    "@vaadin/date-time-picker": "25.3.0-alpha12",
+    "@vaadin/item": "25.3.0-alpha12",
+    "@vaadin/list-box": "25.3.0-alpha12",
+    "@vaadin/radio-group": "25.3.0-alpha12",
+    "@vaadin/select": "25.3.0-alpha12",
+    "@vaadin/test-runner-commands": "25.3.0-alpha12",
     "@vaadin/testing-helpers": "^2.0.0",
-    "@vaadin/text-area": "25.3.0-alpha10",
-    "@vaadin/text-field": "25.3.0-alpha10",
-    "@vaadin/time-picker": "25.3.0-alpha10",
-    "@vaadin/vaadin-lumo-styles": "25.3.0-alpha10",
+    "@vaadin/text-area": "25.3.0-alpha12",
+    "@vaadin/text-field": "25.3.0-alpha12",
+    "@vaadin/time-picker": "25.3.0-alpha12",
+    "@vaadin/vaadin-lumo-styles": "25.3.0-alpha12",
     "sinon": "^22.0.0"
   },
-  "gitHead": "f2833abdf9b613fa0d0ed216830e3f4de87b7dac"
+  "gitHead": "0f0337783efe38332f5dc6a8968f207d2982de4b"
 }

package/src/styles/vaadin-ai-field-marker-base-styles.js

@@ -181,6 +181,65 @@ export const aiFieldMarkerStyles = css`
     }
   }
 
+  /* The confidence indicator: a sibling of the marker slotted into the
+     field's helper text section. The level class name picks the color and how
+     much of the pie icon is filled. */
+  :has(> vaadin-ai-field-marker) > [slot='helper'].ai-confidence {
+    display: flex;
+    align-items: center;
+    gap: var(--vaadin-gap-s);
+    color: var(--_vaadin-ai-field-marker-confidence-color);
+
+    &::before {
+      content: '';
+      flex: none;
+      box-sizing: border-box;
+      width: var(--vaadin-icon-size, 1lh);
+      height: var(--vaadin-icon-size, 1lh);
+      /* The padding insets the pie from the ring: the wedge is clipped to the
+         content box, while the tint fills the whole circle behind it. */
+      padding: calc(var(--vaadin-icon-size, 1lh) / 12);
+      border: 1px solid color-mix(in srgb, currentColor 50%, transparent);
+      border-radius: 50%;
+      background-color: color-mix(in srgb, currentColor 15%, transparent);
+      background-image: conic-gradient(currentColor var(--_vaadin-ai-field-marker-confidence-fill, 0%), #0000 0%);
+      background-clip: content-box, border-box;
+    }
+
+    /* The levels are told apart by how much of the pie is filled, so the base
+       styles keep them in the same neutral color. The themes map the custom
+       properties to their own semantic colors. */
+    &.ai-confidence-low {
+      --_vaadin-ai-field-marker-confidence-color: var(
+        --vaadin-ai-field-marker-confidence-low-color,
+        var(--vaadin-text-color-secondary)
+      );
+      --_vaadin-ai-field-marker-confidence-fill: 25%;
+    }
+
+    &.ai-confidence-medium {
+      --_vaadin-ai-field-marker-confidence-color: var(
+        --vaadin-ai-field-marker-confidence-medium-color,
+        var(--vaadin-text-color-secondary)
+      );
+      --_vaadin-ai-field-marker-confidence-fill: 50%;
+    }
+
+    &.ai-confidence-high {
+      --_vaadin-ai-field-marker-confidence-color: var(
+        --vaadin-ai-field-marker-confidence-high-color,
+        var(--vaadin-text-color-secondary)
+      );
+      --_vaadin-ai-field-marker-confidence-fill: 75%;
+    }
+  }
+
+  /* While the AI is working, the confidence describes a value that is about
+     to be replaced, so hide it along with the marker. */
+  [ai-working] > [slot='helper'].ai-confidence {
+    display: none;
+  }
+
   [ai-working],
   :has(> vaadin-ai-field-marker)::part(input-field),
   :has(> vaadin-ai-field-marker)::part(input-fields),

package/src/vaadin-ai-field-marker.d.ts

@@ -28,6 +28,15 @@ export interface AiFieldMarkerI18n {
    * The tooltip text of the badge button.
    */
   badgeTooltip?: string;
+
+  /**
+   * The texts of the confidence indicator.
+   */
+  confidence?: {
+    low?: string;
+    medium?: string;
+    high?: string;
+  };
 }
 
 /**
@@ -53,20 +62,32 @@ export type AiFieldRevertEvent = CustomEvent<{ value: unknown }>;
  * in progress, set the `working` property to show an "AI is working" shimmer
  * on the field along with a client-side read-only guard.
  *
+ * Set the `confidence` property to show the confidence level of the filled
+ * value (`low`, `medium` or `high`) as an indicator in the field's helper
+ * text section, ahead of a helper the field itself may have. While the
+ * indicator is shown, the field is marked with `has-helper`, so that the
+ * helper text section is laid out the same as for a helper of its own.
+ *
  * ### Styling
  *
- * The following state attribute is set on the field element for styling:
+ * The following state attributes are set on the field element for styling:
  *
- * Attribute    | Description
- * -------------|-------------
- * `ai-working` | Set while an AI is working on the field.
+ * Attribute       | Description
+ * ----------------|-------------
+ * `ai-working`    | Set while an AI is working on the field.
+ *
+ * The confidence indicator is rendered into the field's light DOM as a
+ * `<span>` with the `ai-confidence` class name and the level as an additional
+ * `ai-confidence-low`, `ai-confidence-medium` or `ai-confidence-high` one.
  *
  * The following custom CSS properties are available for styling:
  *
- * Custom CSS property                         |
- * :-------------------------------------------|
- * `--vaadin-ai-field-marker-badge-icon-color` |
- * `--vaadin-ai-field-marker-mask-pos`         |
+ * Custom CSS property                                  |
+ * :----------------------------------------------------|
+ * `--vaadin-ai-field-marker-badge-icon-color`          |
+ * `--vaadin-ai-field-marker-confidence-high-color`     |
+ * `--vaadin-ai-field-marker-confidence-low-color`      |
+ * `--vaadin-ai-field-marker-confidence-medium-color`   |
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
@@ -89,7 +110,13 @@ declare class AiFieldMarker extends I18nMixin<typeof HTMLElement, AiFieldMarkerI
    *   // The accessible label of the badge button and the popover dialog.
    *   badgeLabel: 'AI-provided value',
    *   // The tooltip text of the badge button.
-   *   badgeTooltip: 'Field value modified by AI.\nClick for details'
+   *   badgeTooltip: 'Field value modified by AI.\nClick for details',
+   *   // The texts of the confidence indicator.
+   *   confidence: {
+   *     low: 'Low confidence',
+   *     medium: 'Medium confidence',
+   *     high: 'High confidence'
+   *   }
    * }
    * ```
    */
@@ -105,6 +132,14 @@ declare class AiFieldMarker extends I18nMixin<typeof HTMLElement, AiFieldMarkerI
    * the field is marked with `aria-busy`.
    */
   working: boolean;
+
+  /**
+   * The confidence level of the AI-filled value, shown as an indicator
+   * in the field's helper text section. Possible values are `low`,
+   * `medium` and `high`; when not set, no indicator is shown. The
+   * indicator texts can be localized with the `i18n` property.
+   */
+  confidence: 'high' | 'low' | 'medium' | null;
 }
 
 declare global {

package/src/vaadin-ai-field-marker.js

@@ -11,7 +11,11 @@ import { getDeepActiveElement, getTabbableElements, isKeyboardActive } from '@va
 import { registerCSSProperty } from '@vaadin/component-base/src/css-utils.js';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { DirMixin } from '@vaadin/component-base/src/dir-mixin.js';
-import { addValuesToAttribute, removeValuesFromAttribute } from '@vaadin/component-base/src/dom-utils.js';
+import {
+  addValuesToAttribute,
+  hasNodeContent,
+  removeValuesFromAttribute,
+} from '@vaadin/component-base/src/dom-utils.js';
 import { I18nMixin } from '@vaadin/component-base/src/i18n-mixin.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
 import { SlotStylesMixin } from '@vaadin/component-base/src/slot-styles-mixin.js';
@@ -23,10 +27,13 @@ const DEFAULT_I18N = {
   revert: 'Revert Value',
   badgeLabel: 'AI-provided value',
   badgeTooltip: 'Field value modified by AI.\nClick for details',
+  confidence: {
+    low: 'Low confidence',
+    medium: 'Medium confidence',
+    high: 'High confidence',
+  },
 };
 
-const POPOVER_TRIGGER = ['click'];
-
 // Half of the 1s working shimmer slide (`--vaadin-ai-field-marker-slide` in
 // the base styles), so that held-back values land — and the read-only lock
 // lifts — in the middle of a slide instead of at its edge.
@@ -37,6 +44,14 @@ const MARKER_SLOT = 'ai-field-marker';
 /** Marks the `<style>` element the marker injects into a field's shadow root. */
 const MARKER_STYLE_ATTRIBUTE = 'ai-field-marker-styles';
 
+/**
+ * The class name of the confidence indicator the marker adds to the field's
+ * light DOM; the level goes on a suffixed class name of its own. Prefixed
+ * with `ai-`, since the indicator sits among the application's own children
+ * of the field, where a plain `confidence` or `low` would be ambiguous.
+ */
+const CONFIDENCE_CLASS = 'ai-confidence';
+
 // The position the shimmer's mask is at, animated by the marker's keyframes.
 // Registered here rather than with an @property rule in the marker stylesheet,
 // which is injected into the field's root node: a registration only takes effect
@@ -96,6 +111,9 @@ class DelayedFieldValue {
   /** The queued value, while `#timer` is pending. */
   #queuedValue;
 
+  /** Whether the field's own `value` accessor is currently replaced. */
+  #installed = false;
+
   constructor(field, delay) {
     this.#field = field;
     this.#delay = delay;
@@ -146,12 +164,17 @@ class DelayedFieldValue {
         this.#timer = setTimeout(() => this.#flush(), this.#delay);
       },
     });
+    this.#installed = true;
   }
 
   /** Restores the field's own accessor, applying a queued value right away. */
   uninstall() {
-    if (Object.getOwnPropertyDescriptor(this.#field, 'value')) {
+    // Only remove an own property that this instance defined, so that a field
+    // keeping its value in an own property instead of an accessor — which
+    // `install()` leaves alone — does not lose it.
+    if (this.#installed) {
       delete this.#field.value;
+      this.#installed = false;
     }
     this.#flush();
   }
@@ -204,20 +227,32 @@ class DelayedFieldValue {
  * directly into the marker's light DOM, so that document-level themes
  * and user stylesheets can reach them.
  *
+ * Set the `confidence` property to show the confidence level of the filled
+ * value (`low`, `medium` or `high`) as an indicator in the field's helper
+ * text section, ahead of a helper the field itself may have. While the
+ * indicator is shown, the field is marked with `has-helper`, so that the
+ * helper text section is laid out the same as for a helper of its own.
+ *
  * ### Styling
  *
- * The following state attribute is set on the field element for styling:
+ * The following state attributes are set on the field element for styling:
+ *
+ * Attribute       | Description
+ * ----------------|-------------
+ * `ai-working`    | Set while an AI is working on the field.
  *
- * Attribute    | Description
- * -------------|-------------
- * `ai-working` | Set while an AI is working on the field.
+ * The confidence indicator is rendered into the field's light DOM as a
+ * `<span>` with the `ai-confidence` class name and the level as an additional
+ * `ai-confidence-low`, `ai-confidence-medium` or `ai-confidence-high` one.
  *
  * The following custom CSS properties are available for styling:
  *
- * Custom CSS property                         |
- * :-------------------------------------------|
- * `--vaadin-ai-field-marker-badge-icon-color` |
- * `--vaadin-ai-field-marker-mask-pos`         |
+ * Custom CSS property                                  |
+ * :----------------------------------------------------|
+ * `--vaadin-ai-field-marker-badge-icon-color`          |
+ * `--vaadin-ai-field-marker-confidence-high-color`     |
+ * `--vaadin-ai-field-marker-confidence-low-color`      |
+ * `--vaadin-ai-field-marker-confidence-medium-color`   |
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
@@ -251,6 +286,17 @@ class AiFieldMarker extends SlotStylesMixin(I18nMixin(DirMixin(PolylitMixin(LitE
         type: Boolean,
         value: false,
       },
+
+      /**
+       * The confidence level of the AI-filled value, shown as an indicator
+       * in the field's helper text section. Possible values are `low`,
+       * `medium` and `high`; when not set, no indicator is shown. The
+       * indicator texts can be localized with the `i18n` property.
+       */
+      confidence: {
+        type: String,
+        value: null,
+      },
     };
   }
 
@@ -272,6 +318,20 @@ class AiFieldMarker extends SlotStylesMixin(I18nMixin(DirMixin(PolylitMixin(LitE
   /** The field value captured for the revert event detail. */
   #capturedValue;
 
+  /**
+   * The confidence indicator added to the field's light DOM and rendered
+   * in the field's helper text section. Set while `confidence` is set on
+   * a marked field.
+   */
+  #confidenceNode = null;
+
+  /**
+   * Observes the field's `has-helper` attribute while the confidence
+   * indicator is shown, so that the marker can re-assert it if the field
+   * recomputes it from its own helper content. Created on first use.
+   */
+  #helperStateObserver = null;
+
   /**
    * While in the working state, the elements whose client-side `readonly`
    * state was overridden — the field itself and, for a `vaadin-custom-field`,
@@ -361,7 +421,13 @@ class AiFieldMarker extends SlotStylesMixin(I18nMixin(DirMixin(PolylitMixin(LitE
    *   // The accessible label of the badge button and the popover dialog.
    *   badgeLabel: 'AI-provided value',
    *   // The tooltip text of the badge button.
-   *   badgeTooltip: 'Field value modified by AI.\nClick for details'
+   *   badgeTooltip: 'Field value modified by AI.\nClick for details',
+   *   // The texts of the confidence indicator.
+   *   confidence: {
+   *     low: 'Low confidence',
+   *     medium: 'Medium confidence',
+   *     high: 'High confidence'
+   *   }
    * }
    * ```
    *
@@ -443,6 +509,8 @@ class AiFieldMarker extends SlotStylesMixin(I18nMixin(DirMixin(PolylitMixin(LitE
 
     this.#stopWorking(true);
 
+    this.#removeConfidenceNode();
+
     if (this.#descNode) {
       removeValuesFromAttribute(this.#describedElement, 'aria-describedby', this.#descNode.id);
       this.#descNode.remove();
@@ -477,6 +545,10 @@ class AiFieldMarker extends SlotStylesMixin(I18nMixin(DirMixin(PolylitMixin(LitE
       return;
     }
 
+    if (props.has('confidence') || props.has('__effectiveI18n')) {
+      this.#updateConfidence();
+    }
+
     if (props.has('working')) {
       if (this.working) {
         this.#startWorking();
@@ -487,6 +559,12 @@ class AiFieldMarker extends SlotStylesMixin(I18nMixin(DirMixin(PolylitMixin(LitE
         this.#capturedValue = this.#annotatedValue();
         this.#announcePending = true;
       }
+
+      // The indicator is hidden while working, so the helper text section is
+      // only claimed for it — and the indicator described — once the working
+      // state ends.
+      this.#updateConfidenceDescription();
+      this.#updateFieldHelperState();
     }
 
     // Announce after the update so the announcement reflects a message set in
@@ -510,15 +588,7 @@ class AiFieldMarker extends SlotStylesMixin(I18nMixin(DirMixin(PolylitMixin(LitE
     return html`
       <button id="${this.#badgeId}" class="badge" type="button" tabindex="0" aria-label="${badgeLabel}"></button>
       <vaadin-tooltip for="${this.#badgeId}" text="${badgeTooltip}"></vaadin-tooltip>
-      <vaadin-popover
-        for="${this.#badgeId}"
-        role="dialog"
-        aria-label="${badgeLabel}"
-        .trigger="${POPOVER_TRIGGER}"
-        autofocus
-        theme="arrow"
-        position="end-top"
-      >
+      <vaadin-popover for="${this.#badgeId}" aria-label="${badgeLabel}" autofocus theme="arrow" position="end-top">
         <p class="message">${message}</p>
         <div class="actions">
           <button type="button" tabindex="0" @click="${this.#onRevert}">${revert}</button>
@@ -596,6 +666,10 @@ class AiFieldMarker extends SlotStylesMixin(I18nMixin(DirMixin(PolylitMixin(LitE
       this.#describedElement = describedElement;
     }
 
+    // Apply the confidence indicator directly: on a reconnect no property
+    // change triggers updated(), which handles the first connect.
+    this.#updateConfidence();
+
     // Capture the AI-filled value so the revert event can carry it.
     this.#capturedValue = this.#annotatedValue();
 
@@ -621,6 +695,133 @@ class AiFieldMarker extends SlotStylesMixin(I18nMixin(DirMixin(PolylitMixin(LitE
     return this.#valueDelay ? this.#valueDelay.latestValue : field.value;
   }
 
+  /**
+   * Syncs the confidence indicator in the field's helper text section with
+   * the `confidence` property: a `<span>` slotted into the field's helper
+   * slot, with the `ai-confidence` and `ai-confidence-<level>` class names
+   * and the localized level text as content.
+   */
+  #updateConfidence() {
+    const field = this.#field;
+    if (!field) {
+      return;
+    }
+
+    const level = this.confidence;
+    if (!level) {
+      this.#removeConfidenceNode();
+      return;
+    }
+
+    if (!this.#confidenceNode) {
+      const node = document.createElement('span');
+      node.setAttribute('slot', 'helper');
+      // Hide the indicator from the field's helper slot controller, which
+      // would otherwise evict the field's own helper element in favor of
+      // the indicator. The browser still renders it in the helper slot.
+      node.setAttribute('data-slot-ignore', '');
+      node.id = `ai-field-marker-confidence-${generateUniqueId()}`;
+      // Insert ahead of a helper the field already has, so that the indicator
+      // comes first in the helper text section. A helper added later ends up
+      // after the indicator, since the field appends it.
+      field.insertBefore(node, field.querySelector(':scope > [slot="helper"]'));
+      this.#confidenceNode = node;
+    }
+
+    this.#confidenceNode.className = `${CONFIDENCE_CLASS} ${CONFIDENCE_CLASS}-${level}`;
+    this.#confidenceNode.textContent = this.__effectiveI18n.confidence[level] ?? '';
+    this.#updateConfidenceDescription();
+    this.#updateFieldHelperState();
+  }
+
+  /**
+   * Keeps the indicator's id in the described element's `aria-describedby`
+   * only while the indicator is shown: a visually hidden indicator would
+   * still get read as part of the field's description, although it describes
+   * a value the AI is about to replace.
+   */
+  #updateConfidenceDescription() {
+    const node = this.#confidenceNode;
+    if (!node || !this.#describedElement) {
+      return;
+    }
+
+    if (this.working) {
+      removeValuesFromAttribute(this.#describedElement, 'aria-describedby', node.id);
+    } else {
+      addValuesToAttribute(this.#describedElement, 'aria-describedby', node.id);
+    }
+  }
+
+  /**
+   * Keeps the field's `has-helper` attribute set while the indicator is
+   * shown, since it is content in the field's helper text section although
+   * the field's own helper is not what provides it. The attribute is what
+   * both the field and the themes key their helper text section styles on —
+   * from showing the section at all to placing it above the field for the
+   * `helper-above-field` theme.
+   *
+   * The field recomputes the attribute from its own helper content, which
+   * never includes the indicator, so a recomputation can drop it while the
+   * indicator is still shown. An observer re-asserts it in that case.
+   */
+  #updateFieldHelperState() {
+    const field = this.#field;
+
+    // While the AI is working the indicator is hidden, so the field should
+    // only reserve the helper text section for a helper of its own.
+    if (this.#confidenceNode && !this.working) {
+      field.toggleAttribute('has-helper', true);
+
+      this.#helperStateObserver ??= new MutationObserver(() => {
+        // Read the field live: the observer is reused when the marker moves
+        // to another field, so a captured one could be a previous field.
+        const observedField = this.#field;
+        if (observedField && this.#confidenceNode && !this.working && !observedField.hasAttribute('has-helper')) {
+          observedField.toggleAttribute('has-helper', true);
+        }
+      });
+      this.#helperStateObserver.observe(field, { attributes: true, attributeFilter: ['has-helper'] });
+      return;
+    }
+
+    this.#helperStateObserver?.disconnect();
+
+    // The field keeps the attribute when its own helper provides content,
+    // which it may have gained while the indicator was shown.
+    if (!this.#hasFieldHelper()) {
+      field.removeAttribute('has-helper');
+    }
+  }
+
+  /**
+   * Whether the field has helper content of its own, i.e. helper slot content
+   * other than the indicator. Judged with the same content check the field
+   * itself uses for its `has-helper` attribute.
+   *
+   * @return {boolean}
+   */
+  #hasFieldHelper() {
+    return [...this.#field.querySelectorAll(':scope > [slot="helper"]')].some(
+      (node) => node !== this.#confidenceNode && hasNodeContent(node),
+    );
+  }
+
+  /** Removes the confidence indicator. */
+  #removeConfidenceNode() {
+    const node = this.#confidenceNode;
+    if (!node) {
+      return;
+    }
+
+    if (this.#describedElement) {
+      removeValuesFromAttribute(this.#describedElement, 'aria-describedby', node.id);
+    }
+    node.remove();
+    this.#confidenceNode = null;
+    this.#updateFieldHelperState();
+  }
+
   /**
    * Enters the "AI is working" state: shows the shimmer and makes the field
    * read-only on the client so the user cannot edit a value the AI is about
@@ -673,9 +874,6 @@ class AiFieldMarker extends SlotStylesMixin(I18nMixin(DirMixin(PolylitMixin(LitE
    */
   #stopWorking(immediate = false) {
     const field = this.#field;
-    if (!field) {
-      return;
-    }
 
     if (this.#restoreTimer != null) {
       // Already winding down. Finish it now when the marker is going away, so