[Tracking] Modern field stroke state model for Net11 editable controls (TextBoxBase)

[ricardobossan]

Goal

Replace the current flat, ForeColor-driven border and the primitive bottom-clipped focus ring on VisualStylesMode.Net11 editable controls with a proper per-state stroke model: a WinUI-style elevation border with distinct Rest, Hover, Focused, Disabled, and ReadOnly treatments; colors derived independently of ForeColor via linear-light overlay compositing; a stronger and thicker bottom elevation edge; an accent focus edge at >= 2 DIP; and hover tracking. High Contrast uses system colors. This issue is the tracking item and definition of done for that work.

Current state (base af0c793)

Editable controls under Net11 (TextBox, MaskedTextBox, RichTextBox, all via TextBoxBase) paint their modern non-client frame in TextBoxBase.OnNcPaint:

• One flat stroke: the border color is the control's ForeColor (adornerColor = ForeColor), one pen, one thickness on all four sides. No elevation edge.
• Focus is a bottom-clipped copy of the same rounded stroke at the same thickness, color animated ForeColor -> accent (AnimatedFocusIndicatorRenderer.DrawRoundedFocusIndicator). FixedSingle uses repeated horizontal bottom lines.
• Rest, Hover, Disabled, and ReadOnly are visually identical (all ForeColor); Hover is not tracked.
• The existing shared blend (PopupButtonColorMath.Blend) interpolates encoded sRGB, so it cannot produce perceptually-correct overlays; new linear-light math is required.

Scope

TextBoxBase's Net11 non-client paint path: TextBox, MaskedTextBox, RichTextBox.

Out of scope (separate follow-ups)

• ComboBox: a WM_PAINT client-area adapter, not an NC-paint caller.
• UpDownBase / UpDownEdit: separate client-area implementation.
  Coordinate a shared visual target with these so a TextBox does not diverge from an adjacent ComboBox or NumericUpDown.

Plan (one migration step at a time)

Behavior-preserving refactor first (Steps 1 and 2), then the one visible change (Step 3). The step and sub-step labels below are the reference scheme used across the linked PRs and comments.

Step 1: Introduce the model, wired to nothing. Add a ModernFieldStrokeState enum, a ModernFieldStroke record, a context, a GetStroke resolver (state precedence Disabled > Focused > ReadOnly > Hover > Rest), and a per-control cache, with a compatibility mapping that reproduces today's pixels, plus unit tests. No paint path calls it; zero visual diff.

Step 2: Route the paint through the resolver. Change TextBoxBase.OnNcPaint to obtain its stroke from GetStroke, with the compatibility mapping still on. Still zero visual diff (prove it with a pixel baseline captured before this step).

Step 3: Apply the real visuals. Deliverable 1 does this as a single commit; proposed here as three independently reviewable sub-steps:

• Step 3a (color model): remove ForeColor from the stroke, add linear-light overlay compositing, and apply the Rest, Disabled, and ReadOnly colors, plus the High Contrast bypass.
• Step 3b (focus): the accent-colored bottom edge and the DPI-scaled focus thickness (at least 2 DIP).
• Step 3c (hover): the new hover tracking and repaint, plus the Hover state color.

Open decisions

• High Contrast focus color: keep SystemColors.Highlight (current) vs switch to SystemColors.ControlText. Accessibility-affecting; recommend keeping Highlight unless validated.
• Focus thickness: max(2 DIP, configured focus metric); and whether the thickness change snaps or animates (color already animates 200 ms).
• Hover detection mechanism for the non-client border.
• Shared visual target with the out-of-scope ComboBox / UpDown.

Related

• ForeColor incorrectly affects the border color of editable controls under VisualStylesMode.NET11 #14847: ForeColor incorrectly affects the border color of editable controls (the narrow resting-color slice).
• Fix editable control border color in NET11 visual styles #14853: fixes ForeColor incorrectly affects the border color of editable controls under VisualStylesMode.NET11 #14847 by replacing ForeColor with a shared ModernControlColorMath.TextControlBorderColor in TextBoxBase, ComboBox.ModernComboAdapter, and UpDownBase. This is the first narrow step of this task and should land first; afterward, Step 1's compatibility mapping rebaselines its resting and disabled endpoints onto TextControlBorderColor / GetDisabledBorderColor.
• ONLY FOR TESTING: Integration-4 for the new .NET 11 API #14792: introduced Net11 editable-control rendering (origin).
• A design/analysis (Deliverable 1) informed this plan.

[ricardobossan]

@KlausLoeffelmann @LeafShi1 @SimonZhao888 @Olina-Zhang

Quick proof of concept to check the direction before I build the real model. This is throwaway, not a PR.

What it shows: an elevation bottom edge on the Net11 editable border. The bottom is stronger and thicker at rest. On focus it turns the accent color and gets thicker. That replaces today's flat, uniform border, whose color comes from ForeColor.

Please don't read it as the implementation. It skips several things on purpose. The rest overlay is a plain alpha hack, not linear-light compositing. The side and top edges and ForeColor are untouched. Disabled and read-only aren't styled. There's no hover state. Those land in Steps 3a, 3b, and 3c in the plan above.

I mainly want a direction check before I invest in the zero-diff refactor:

1. Does the elevation bottom edge read right as the target look?
2. Does the accent focus thickness feel right, too thick, or too thin? (This maps to the ">= 2 DIP" open decision.)
3. Any expectation for hover, since this proof of concept doesn't cover it?

[LeafShi1]

@KlausLoeffelmann @LeafShi1 @SimonZhao888 @Olina-Zhang

Quick proof of concept to check the direction before I build the real model. This is throwaway, not a PR.
...
I mainly want a direction check before I invest in the zero-diff refactor:

1. Does the elevation bottom edge read right as the target look?
2. Does the accent focus thickness feel right, too thick, or too thin? (This maps to the ">= 2 DIP" open decision.)
3. Any expectation for hover, since this proof of concept doesn't cover it?

My suggestion:

1. Too much of the area is highlighted in the "Focus" state; highlighting just the bottom border should suffice.
2. In the "Normal" state, the bottom border is 2 pixels wide. In the "Focus" state, the bottom border is highlighted and its width increases to 4 pixels; ensure the extra 2 pixels are added outwardly so as not to affect the TextArea itself, and use the Accent Color.
3. In the "Hover" state, change only the color—do not alter the border thickness. Visually enhance the color by only 10%–20% (consider using a slightly darker shade).

State	Top / Left / Right	Bottom Stroke	Background
Rest	Light Gray 2px	Darker Gray 2px	Normal Surface
Hover	Slightly Darker	Slightly Darker	Slightly Darker
Focus	Same as Hover	Accent Color, 4 DIP (outside)	Normal Surface
Disabled	Disabled Gray	Disabled Darker Gray	Disabled Surface
ReadOnly	Same as Rest	Same as Rest	ReadOnly Surface

[KlausLoeffelmann]

IMPORTANT!

High Contrast uses system colors.

HighContrast automatically opts out of VisualStyles and DarkMode!!

[KlausLoeffelmann]

I quite second what @LeafShi1 wrote.
We should thrive this kind of rendering for focus/non-focus for RC2 with higher priority, so we'd still have time to fine-tune:

For ClassicMode, I have to say, the contrast of the border is not prominent enough for my taste. Wouldn't that be a contrast violation for WinForms, @Olina-Zhang? I would go for a compromise between what we have now, and what Windows renders natively in WinUI.

For DarkMode, I think the contrast is OK.

@ricardobossan: Could you please create sub-issues for this, and see, that we can address those with highest priority? Holler, if you want me to jump in!

[ricardobossan]

Thanks @KlausLoeffelmann . On High Contrast: since it opts out of VisualStyles and DarkMode, the modern paint path never runs there, so the resolver's HC branch was dead code. Removed it and fixed the PR note. On the light-mode border: measured with Accessibility Insights, the visible bottom edge is 1.744:1 and fails WCAG 1.4.11, as WinUI's own borders do, so I raised it to about 4.5:1. @Olina-Zhang , could you confirm the WCAG-safe target, or whether we take the WinUI-style exception?

Creating the sub-issues now at highest priority for RC2 and linking PR #14919.

[Olina-Zhang]

@ricardobossan @KlausLoeffelmann The contrast ratio of control borders should be at least 3:1 against adjacent colors per WCAG 1.4.11 (Non-text Contrast). Based on that requirement, 4.5:1 is a WCAG-safe value. See: WCAG 1.4.11 Non-text Contrast.