Skip to content

feat: add AI field marker - #12351

Merged
tomivirkki merged 51 commits into
mainfrom
feat/ai-field-marker
Aug 10, 2026
Merged

tomivirkki merged 51 commits into
mainfrom
feat/ai-field-marker

Conversation

@tomivirkki

Copy link
Copy Markdown
Member

Summary

  • Adds an internal <vaadin-ai-field-marker> element for annotating a field whose value was filled by AI: appending it to a field draws a badge with a tooltip and an explanation popover that lets the user revert the value, and removing it clears the mark. A hidden description and a live announcement expose the same information to screen readers.
  • A working state covers the fill itself: the field shows a shimmer and is locked read-only on the client so the user cannot edit a value the AI is about to overwrite, and value sets land in sync with the animation.
  • The marker is a building block for Flow AI form-filling integration.

🤖 Generated with Claude Code

tomivirkki and others added 30 commits August 4, 2026 15:49
Field-highlighter is reserved for collaboration. Add a dedicated, accessible AI-filled annotation: a field highlight and badge with a popover that explains the AI fill and lets the user revert it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
A screen reader ignores aria-description when aria-describedby is present, so the AI note was dropped on fields with helper or error text. Reference it from aria-describedby instead so both are read.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Localizing the marker required passing options to every mark() call. Add AiFieldMarker.setDefaults() to set the texts once for all fields; per-call options still take precedence.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Allow slotting custom content into the popover via slot="ai-field-marker-popover-content" on the field, so a server-side framework can render content there from the field's light DOM.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The marker renders in the field's light DOM, so its clicks reached the
field host, and revert called focus() on the host. Fields that act on a
host click or focus, such as date-picker, opened their overlay.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A new request replaces the value the existing marker annotates, so its
badge and glow were stale for the duration. Restoring the mark when the
working state ends keeps it usable for a fill that is cancelled or fails.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Installing the interceptor without a delegate made `'value' in field` true,
so the guarded reads in connectedCallback and updated() started throwing.

Co-Authored-By: Claude <noreply@anthropic.com>
The interceptor was only removed by a delayed set that actually fired, so a
working state that filled nothing left it installed and delayed the host's
next assignment. A set still queued when the marker is removed is now applied
right away instead of landing after the field is no longer annotated.

Co-Authored-By: Claude <noreply@anthropic.com>
Re-capturing on leaving the working state read the field through the delaying
accessor, which still reported the value the pending fill was about to replace,
so the revert event carried the pre-fill value.

Co-Authored-By: Claude <noreply@anthropic.com>
The restore was scheduled per element with no handle on the timer, so
re-entering the working state during the wind-down captured the locked state as
the original, unlocked the field mid-fill and left it read-only afterwards. A
pending restore also outlived the marker and overwrote later read-only changes.

Co-Authored-By: Claude <noreply@anthropic.com>
Resolving the described element through inputElement/focusElement left group
and composite fields without any description: they expose neither, and point at
the element carrying their own descriptions through ariaTarget.

Co-Authored-By: Claude <noreply@anthropic.com>
A field derived from custom-field ships under its own tag name, so the tag
check left its inputs editable during a fill.

Co-Authored-By: Claude <noreply@anthropic.com>
The re-render on reconnect was requested after the early return for a parent
that is not a field, so the badge and popover rendered for the previous field
stayed in the shadow root.

Co-Authored-By: Claude <noreply@anthropic.com>
A marker attached before the field was upgraded found no shadow root and stayed
inert forever, so a field whose module loads late was never marked.

Co-Authored-By: Claude <noreply@anthropic.com>
The keyframes were pushed onto the field's adoptedStyleSheets, which the
themable infrastructure replaces wholesale on a Lumo stylesheet load or a theme
switch. Losing them left the field's input masked but never animating, with
nothing to re-adopt them.

Co-Authored-By: Claude <noreply@anthropic.com>
The @Property rule sat in the stylesheet adopted into the field's root node,
which is a shadow root for a nested field, where such a rule is ignored. The
property was then unregistered, so it neither interpolated nor had its initial
value and the shimmer broke.

Co-Authored-By: Claude <noreply@anthropic.com>
The styles module exports three constants but the type declarations named only
two, so importing the third failed to compile.

Co-Authored-By: Claude <noreply@anthropic.com>
tomivirkki and others added 4 commits August 4, 2026 16:28
The themable infrastructure replaces adoptedStyleSheets wholesale, which
dropped the marker styles for a field nested in another component's
shadow root. Inject them as a style element instead, the same way the
keyframes already dodge this in the field's own shadow root.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The hand-copied rule dropped the !important markers, so a document-level
rule with higher specificity could make the hidden description visible.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A click-triggered popover only closes on outside pointer interaction or
Esc, so tabbing on to the next field left it open and popovers of
several marked fields could pile up during keyboard navigation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@tomivirkki
tomivirkki marked this pull request as draft August 4, 2026 13:46

@vaadin-review-bot vaadin-review-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the changes — left 4 comments.

Finding
⚠️ A value queued during the working state overwrites a newer value the host sets during the shimmer wind-down.
⚠️ The working-shimmer input-area reveal never applies to vaadin-custom-field, whose input wrapper is part="input-fields".
🧹 New CSS custom properties --color1 / --color2 are not namespaced with the component.
🧹 injectMarkerRootStyles re-implements the per-root <style> injection already provided by SlotStylesMixin.

@knoobie

knoobie commented Aug 4, 2026 •

Copy link
Copy Markdown
Contributor

High Level Suggestion: while clearly needed for AI, how about changing the scope a little bit and start with a marker that a field was changed (by whoever, human, code (auto fill / correct) or ai) and let the developer decice what the reason for this change was (and a way to define what's shown in the overlay, e.g. old value, action to revert, explanation...)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@tomivirkki

Copy link
Copy Markdown
Member Author

Thanks for the suggestion @knoobie. We discussed a more generic "value changed" marker, but making it multi-purpose would need more design work. The use cases beyond AI are still vague at this point, and we don't want to guess that API now. So we're going to continue with the AI-specific approach for the time being.

Since the component is internal, we keep the possibility open to refactor it later, possibly into a multi-purpose marker like you describe. Could you open a feature request with the use cases you have in mind?

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@tomivirkki
tomivirkki marked this pull request as ready for review August 5, 2026 12:52

@vaadin-review-bot vaadin-review-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the changes — left 7 comments.

Finding
⚠️ Reverting an AI value on a vaadin-radio-group never returns focus to the group.
⚠️ The AI message is re-announced to screen readers every time the marked field is re-attached to the DOM.
⚠️ Multiple markers on one field do not coordinate the shared read-only lock or value interceptor.
⚠️ A read-only change made by the host during the working wind-down is silently reverted.
⚡ customElements.whenDefined(...).then() pins the marker and its parent in memory if the tag never upgrades.
🧹 The if (locked) guard in #restoreLockedElements can never be false.
🧹 The popover-close snippet is copy-pasted in the focusout handler and #onRevert.

tomivirkki and others added 2 commits August 6, 2026 09:17
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
# Conflicts:
#	packages/field-highlighter/package.json
@sonarqubecloud

sonarqubecloud Bot commented Aug 7, 2026

Copy link
Copy Markdown

@ugur-vaadin ugur-vaadin left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: the colors in dark mode might be a little muted and hard to distinguish

@tomivirkki
tomivirkki merged commit 46f0eb5 into main Aug 10, 2026
11 checks passed
@tomivirkki
tomivirkki deleted the feat/ai-field-marker branch August 10, 2026 09:41
@vaadin-bot

Copy link
Copy Markdown
Collaborator

This ticket/PR has been released with Vaadin 25.3.0.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants