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.

[alice-i-cecile]

It's an important use case! It appears that these were added in #9931, by @ickshonpe :)

I can definitely see the argument to not break existing users. I'm not super keen on having "two subtly distinct ways to draw outlines". I had completely forgotten that this a) had other uses and b) was added much earleir.

The limitations of the initial "just use Outline" design are pretty severe though. We can fix the z-ordering by changing how Outline works, probably in a way that would be better for all users. The "restore previous state bug" could also be solved: just throw some caching at it for now.

Proposed plan:

1. Use Outline for now.
2. Add a simple cache to restore the previous outline when unfocused.
3. Fix outline z-ordering later, somehow.

Does that sound agreeable to both of you?

[viridia]

Here's a sketch of a completely over-the-top solution (NOT proposing that we do this now):

• We introduce a new kind of entity called a "Decoration". Outlines are one kind of decoration, drop shadows are another kind.
• Decorations are not Nodes - rather they are attachments to Nodes which draw cause additional polygons to be drawn.
• We introduce a new relation type, DecoratedBy. This relates a node to all of its decorations.
• This means that a node can have as many decorations as you like: multiple outlines, multiple drop shadows, and so on. Each outline or shadow can be a different color, different size, and so on.
• Decorations can have a Z-index component.
• Decorations are invisible to the picking system (for now)

What I particularly like about this proposal is that it goes far beyond the restrictions of the web. The web was originally designed, after all, to present documents like a desktop publishing system. But Bevy is a media engine, and shouldn't be trapped in a document mind-set.

[ickshonpe]

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

Outlines aren't anything special, they are just borders which don't take up any space in the layout. They were very easy to implement and they are useful when you want to distinguish a particular node or something.

[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.

[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.