Focus rings for feathers widgets and core widget examples.

[viridia]

Objective

Add focus rings for:

• Core widget examples
• Feathers widgets

Part of #19236

@alice-i-cecile

[viridia]

BTW, you know what would be awesome? If outlines had a z-index offset :)

[ickshonpe]

BTW, you know what would be awesome? If outlines had a z-index offset :)

I think using the outlines API probably just isn't a good fit for this. We could add another component or add a system to directly extract the focus rings for rendering. That would allow for arbitrary z-ordering.

[ickshonpe]

We could use an extraction system instead and draw the focus ring directly for the current InputFocus. Made a quick prototype:

pub fn extract_focus_ring(
    mut commands: Commands,
    mut extracted_uinodes: ResMut<ExtractedUiNodes>,
    focus: Extract<Res<InputFocus>>,
    theme: Extract<Option<Res<UiTheme>>>,
    uinode_query: Extract<
        Query<
            (
                &Node,
                &ComputedNode,
                &InheritedVisibility,
                &UiGlobalTransform,
                Option<&CalculatedClip>,
                &ComputedNodeTarget,
            ),
            With<TabIndex>,
        >,
    >,
    camera_map: Extract<UiCameraMap>,
) {
    let mut camera_mapper = camera_map.get_mapper();

    let Some(focused_entity) = focus.0 else {
        return;
    };
    let Ok((node, computed_node, inherited_visibility, transform, maybe_clip, target)) =
        uinode_query.get(focused_entity)
    else {
        return;
    };

    if !inherited_visibility.get() || node.display == Display::None {
        return;
    }

    let ring_color = theme
        .as_ref()
        .map(|theme| theme.color(bevy_feathers::tokens::FOCUS_RING))
        .unwrap_or(bevy_color::palettes::tailwind::BLUE_700.into());

    let Some(extracted_camera_entity) = camera_mapper.map(target) else {
        return;
    };

    let ring_width = 2. * target.scale_factor();
    let outer_distance = 2. * ring_width;
    let ring_size = computed_node.size() + outer_distance;
    let compute_radius = |node_corner_radius| {
        if 0. < node_corner_radius {
            node_corner_radius + outer_distance
        } else {
            0.
        }
    };

    let ring_radius = ResolvedBorderRadius {
        top_left: compute_radius(computed_node.border_radius.top_left),
        top_right: compute_radius(computed_node.border_radius.top_right),
        bottom_right: compute_radius(computed_node.border_radius.bottom_right),
        bottom_left: compute_radius(computed_node.border_radius.bottom_left),
    };

    extracted_uinodes.uinodes.push(ExtractedUiNode {
        z_order: computed_node.stack_index as f32 + stack_z_offsets::FOCUS_RING,
        render_entity: commands.spawn(TemporaryRenderEntity).id(),
        color: ring_color.into(),
        rect: Rect {
            max: ring_size,
            ..Default::default()
        },
        image: AssetId::default(),
        clip: maybe_clip.map(|clip| clip.clip),
        extracted_camera_entity,
        item: ExtractedUiItem::Node {
            transform: transform.into(),
            atlas_scaling: None,
            flip_x: false,
            flip_y: false,
            border: BorderRect::all(ring_width),
            border_radius: ring_radius,
            node_type: NodeType::Border(shader_flags::BORDER_ALL),
        },
        main_entity: focused_entity.into(),
    });
}

branch is here: https://github.com/ickshonpe/bevy/tree/focus_ring_extraction

It doesn't support support the sub-focus for the checkbox but marker components could be added to signal a descendant should be outlined instead.

[ickshonpe]

Another alternative would be to have a separate entity, something like:

        (
            FocusRingNode,
            Node {
                position_type: PositionType::Absolute,
                left: Val::Px(0.),
                right: Val::Px(0.),
                top: Val::Px(0.),
                bottom: Val::Px(0.),
                ..Default::default()
            },
            Outline {
                color: theme.color(tokens::FOCUS_RING),
                width: Val::Px(2.0),
                offset: Val::Px(2.0),
            },
        )

And then when input focus changes, reparent the FocusRingNode to the new entity. There would also need to be a system that synchronised the border radii. Then you can set an arbitrary zindex on the ring node, and there would be no need to remove the outline from the previous entity.

[viridia]

I think I'd like to put this issue aside for now.

Using outlines does cause a minor cosmetic problem when using segmented buttons (the adjacent button renders on top of the outline). However, most users will never see this, as focus outlines are disabled until you actually use tab navigation. Other than that minor glitch, outlines work pretty well.

A different approach is to temporarily modify the z-index of the focused button.

In any case, I only mentioned this as speculation; I didn't actually expect to get a solution :)

[alice-i-cecile]

I don't like reusing Outline for this: it causes z-ordering issues, and because it's used for other things, you have to be careful of bugs around restoring the outline when removing focus.

I think that a separate entity with a dedicated component is going to be a much better foundation.

[viridia]

If that's the case, then what are outlines for?

Note that I didn't implement focus rings for core widgets, because of exactly this: core widgets aren't supposed to make assumptions about what styling decisions the client is going to make, whether or not they want to use outlines for focus or some other purpose. The place where I used outlines is (a) in examples, and (b) in the feathers widgets -- both of which presumably "own" their styling.

Sure, we can make something that spawns an absolutely-positioned child entity that inflates the parent's box and draws a border, copying over the border radius (although it will get tricky because we want to increase the radius value by the offset).

But my question then is, why did we add the outlines feature at all? I mean, you could make the argument that anyone who uses outlines for any reason is denying someone else the use of outline for some other reason.

I should note that outlines on the web have exactly this same problem, but I don't think that lets us off the hook; rather I think it means that we're copying the web's mistakes.

[alice-i-cecile]

But my question then is, why did we add the outlines feature at all?

That's a very good point.

What if we rename the outline component to less of an attractive nuisance: something like FocusOutline? Then, point to Border in the docs for other uses.

We can then change the implementation to use multiple entities and have better z-layering in follow-up.

[ickshonpe]

Sure, we can make something that spawns an absolutely-positioned child entity that inflates the parent's box and draws a border, copying over the border radius (although it will get tricky because we want to increase the radius value by the offset).

There's no need to recalculate the border-radius when using outlines for this. It just needs to match the border-radius of the parent. The system for updating the FocusRingNode's border-radius would be very simple, just query for its parent's border-radius and copy it.

[viridia]

I don't think we need to solve the "restore previous outline when unfocused" problem right now. We can solve this later when we implement a more robust way of doing focus rings.

My reasoning is this: the use of outlines to implement focus rings is limited to the following cases:

• examples (specifically core_widgets and input_focus examples).
• feathers

Neither of these cases permits conflicting uses of outlines, but for different reasons. In the case of examples, the user can't re-use the components. In the case of feathers, we can simply declare by fiat that we "own" the outline (this is the benefit of having an opinionated widget collection).

If someone comes along later and says, "no I really want to use a feathers button but I want my own outlines for some different purpose" we can solve it then.

[viridia]

@ickshonpe @alice-i-cecile So I went ahead and implemented the "focus outline as child entity" solution...and it doesn't solve the problem! Well, it doesn't solve the Z-ordering problem.

Using a local ZIndex doesn't do anything: it only affects order relative to siblings, and since the focus outline entity is a child, it doesn't have any siblings.

Using GlobalZIndex is problematic for different reasons: since there's no way for me to know the z-index of the parent, I have to pick some hard-coded value for the z-index for all outlines. I could pick some huge number and make the outlines always be on top, but what if I don't want the outline on top? Like, what if I want a tooltip or other kind of overlay to be above the focus outlines?

What we need is a RelativeGlobalZIndex!

[ickshonpe]

Setting a GlobalZIndex doesn't seem great.
Maybe if it just walks up the tree raising the local ZIndex of all the focused elements ancestors as well? There could be some component that automatically moves not only the local node but also its ancestors to the top of the local draw order.

[viridia]

I think for now let's just punt and solve it later. I worry about trying to shave too many yaks in one PR.

[alice-i-cecile]

I don't like reusing Outline for this: it causes z-ordering issues, and because it's used for other things, you have to be careful of bugs around restoring the outline when removing focus.

I think that a separate entity with a dedicated component is going to be a much better foundation.

[viridia]

@alice-i-cecile @ickshonpe I've completely re-written this PR from scratch. Please re-review.

[ickshonpe]

Get a stack overflow when I tried to run the feathers example with the latest version. The trivial example I used for some basic testing worked fine though.

I still think that adding nodes to the tree to display the focus rings is the wrong approach. They only need to be drawn, they don't need to be part of the layout. Then there's no need for any synchronisation, there aren't any conflicts with measure funcs, and the extraction function can automatically choose the right z-depth.

[ickshonpe]

The name "Anchor" is usually used to refer to anchor points, maybe something else would be clearer. VisibleFocusOutline?

[viridia]

I wanted a name that suggests this is not an outline, but rather an attachment point for an outline.

[ickshonpe]

Maybe -Mount or -Base?

I'd prefer an alternative if there's a good one but it's not super important and I'm fine with using -Anchor if you aren't happy with anything else. It's just that everywhere else an "anchor" means an attachment at a specific geometric point, instead of fit around this node like it does here.

[ickshonpe]

Nodes with a measure func like Text entities don't like having children, if a text node is given a focus outline like this it will probably collapse to zero size.

[ickshonpe]

I don't mean to sound like I hate this that much. I think it's fine for now, we can merge it and move on.
I think I've worked out some very simple workarounds for the measure func and draw ordering problems that I could implement as follow up PRs.

[viridia]

I don't mean to sound like I hate this that much. I think it's fine for now, we can merge it and move on. I think I've worked out some very simple workarounds for the measure func and draw ordering problems that I could implement as follow up PRs.

Well, one option for the short term is to go back to using outlines instead of child entities. The same general system function will work either way, we don't have to change the API. It doesn't solve the Z-index problem, but if it's temporary I don't care.

[ejrh]

Get a stack overflow when I tried to run the feathers example with the latest version. The trivial example I used for some basic testing worked fine though.

Hi @ickshonpe what platform were you running the example on? Sounds like the same issue as #20571.

[ickshonpe]

Get a stack overflow when I tried to run the feathers example with the latest version. The trivial example I used for some basic testing worked fine though.

Hi @ickshonpe what platform were you running the example on? Sounds like the same issue as #20571.

Yep it's the same issue definitely, stackoverflow on windows.

[viridia]

@alice-i-cecile @ickshonpe I'm attempting to revive this PR. I've rebased it against the current main.

I think this is probably good enough for the moment: it's better than not having focus rings at all, and trying to do an "ideal" solution is going to be a lot more complex.

[alice-i-cecile]

I can live with this for now.