"Primary" and destructive action buttons

[dclaux]

Release	Renderer status	Tasks status
1.2	✔️ .NET (#1972) ✔️ Android (#1970) ✔️ iOS (#1971) ✔️ TS (#2435) ✔️ UWP (#2227)	✔️ Shared (#1968)

Solves requests

• "Primary" and destructive action buttons (Request: "Primary" and destructive action buttons #2025)

Solution

Add a style property to all actions. The Style enumeration will initially support only three values, but we could add more styles in the future.

Schema

New property on Action

Property	Type	Required	Description
style	ActionStyle	false	Controls the style of an Action, which influences how the action is displayed, spoken, etc

Other property name ideas...

• category
• appearance - No, because this could have non-appearance related behaviors. Like when spoken, destructive could use a different tone.
• significance
• emotion
• sentiment

Concerns around style?

• We might want to use style for something else, like a "raised" button vs a "flat" button. Nevertheless, style seems like the best choice.

ActionStyle enum

Value	Description
default	Action is displayed as normal
positive	Action is displayed with a positive style (typically the button becomes accent color)
destructive	Action is displayed with a destructive style (typically the button becomes red)

Research on enum value names...

• Android does "positive" and "negative" on their dialogs, and "neutral" for normal
  • Why not "negative"?
    • Because sometimes authors want to display a "delete" button, which isn't exactly negative... it's destructive
• UWP docs mention "destructive", but they don't have anything baked into the API
• Bootstrap has "default", "primary", and "danger"
  • Why not "primary"?
    • Because primary implies that it also gains focus. Sometimes authors might want to have the cancel button as the primary focused button, but the Overwrite button should get the preferred visual treatment
• iOS uses "destructive" on their ActionSheet API
• No one seems to use "emphasized"

This is different from choosing the default action, since sometimes you want the destructive action (like deleting) to be the default action.

Host Config

None. There's already no host config for specifying background colors of actions today. This should all be done using native styling.

Down-level impact

For authors: Low. Actions will still appear, just not with the style behavior.

For hosts: Breaking change. If host is currently natively styling buttons, and now a new primary button comes in, the new button has a new styling name key. Therefore, the host's current styling won't be applied. Hosts need to update their native styling so that when they receive a style, the button at least looks like a default button.

Renderer Requirements

1. A renderer should have a default appropriate rendering for these styles. For example, using accent color for emphasized, and red for destructive.
2. A renderer must output the appropriate styling name on the action, so that hosts can natively style the buttons. For example, a default button might get a style name of Action, but an emphasized button might get a style name of Action.Positive (or however the native platform styling naming convention works)

Auto-generated task status

• Shared
• .NET
• Android
• iOS
• TS
• UWP

[matthidinger]

We should also consider keyboarding experience as well. a Primary action could be wired up to Enter, and desstructive could be Esc

[dclaux]

Here is another suggestion for naming the property:
"emphasis": "none" | "positive" | "destructive" with "none" being the default.

Other than that spec looks fine. One thing that isn't mentioned is whether several actions can have a "positive" or "destructive" emphasis. My opinion is we should simply allow it.

[almedina-ms]

where should the accent color and the destructive button color be taken from? I've seen color configurations for containers but there's no default color configurations for a general case

[khouzam]

After some discussion, I think that the default behaviors should be:

1. Positive action changes the background to the Accent color
2. Destructive action changes the foreground to the Attention color from the host config.

Changing the background on both could lead to both types of actions having the same or similar background color and causing confusion. I'm using Red as my accent color on Windows.

[khouzam]

We've been discussing this feature and I wanted to propose an extensibility point that hosts could support. If the card author specifies another sentiment value than the ones specified here, the renderers would still try to apply the sentiment as a style to the action. This would allow for a host to easily support more sentiments through an efficient extensibility model.

For example, in the UWP renderer, the host can pass a resource dictionary with styles. Having Adaptive.Action.Positive override the default style for positive actions. If the host passes other such styles to the renderer, these styles could be applied for new sentiments. This gives the host the option of supporting more sentiments that the card author can leverage if it knows about them.

The same thing can be applied to the JavaScript renderer with CSS classes.

Thoughts?

[dclaux]

@khouzam I don't mind doing that. The way I see it, there would be a way in HostConfig to declare supported custom sentiment names:

{
    ...
    "customSentiments": [ "custom1", "custom2", ... ]
    ...
}

At runtime, the renderer would check that a specified sentiment name in an action is declared in HostConfig; if so, it would apply the corresponding style (in HTML, simply use the matching CSS class) and if not it would use the default sentiment style.

Is that what you have in mind?

[andrewleader]

DECISION: For the action “sentiment” property, consensus was we should rename the property to “style”. Enum values remain the same (but the enum itself should be renamed to ActionStyle), and the values in it are different from ContainerStyle

{
  “type”: “Action.Submit”,
  “style”: “default” | “positive” | “destructive”