feat: add confidence indicator to AI field marker

dev/ai-field-marker.html

@@ -74,6 +74,8 @@ <h2 class="heading">AI-filled fields</h2>
           // Show the "AI is working" state while the fill is in progress.
           const marker = document.createElement('vaadin-ai-field-marker');
           marker.working = true;
+          // Show the confidence level of the filled value in the helper section.
+          marker.confidence = ['low', 'medium', 'high'][Math.floor(3 * random())];
           field.appendChild(marker);
         });
 

packages/aura/aura.css

@@ -11,6 +11,7 @@
 @import './src/components/input-container.css';
 
 @import './src/components/accordion-details.css';
+@import './src/components/ai-field-marker.css';
 @import './src/components/app-layout.css';
 @import './src/components/avatar.css';
 @import './src/components/badge.css';

packages/aura/src/components/ai-field-marker.css

@@ -0,0 +1,5 @@
+:has(> vaadin-ai-field-marker) {
+  --vaadin-ai-field-marker-confidence-low-color: var(--aura-red-text);
+  --vaadin-ai-field-marker-confidence-medium-color: var(--aura-yellow-text);
+  --vaadin-ai-field-marker-confidence-high-color: var(--aura-green-text);
+}

packages/field-highlighter/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),

packages/field-highlighter/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 {