New spacing model

[dclaux]

Implementation status

• TypeScript (PR New spacing model #463)
• UWP
• .NET (PR Final dotnet 1.0 items #718)
• iOS
• Android
• Documentation

Design proposal

In order to accommodate for more scenarios, we propose to make it possible to select from a wider ranger of spacing between elements, so as to achieve more subtle or more marked separations. At the same time, we propose to separate the concept of "separator" from spacing itself (currently, to get a separator line, one needs to use the "strong" separation.

So we propose the following:

• Remove the "separation" property everywhere
• Remove separation definitions from HostConfig
• Remove strongSeparation from HostConfig
• Introduce a "spacing" enum property available on any card element
• Remove HostConfig.adaptiveCard.padding as it is replaced with one of the named spacing
• Introduce a "separator" property, available on any card element
• Introduce spacing definitions in HostConfig
• Introduce separator thickness and color definitions in HostConfig

Card schema changes

Removed

• All separation properties
• Separation enumeration

New properties on every element

Property	Type	Description
spacing	Spacing	The amount of space the element should be separated from the previous element. Default value is "default"
separator	bool	Indicates whether there should be a visible separator (e.g. a line) between the element and the one before it.

Spacing enumeration

Spacing = "none" | "small" | "default" | "medium" | "large" | "extraLarge" | "padding"

The padding value means "same as card padding". This is to help card authors design cards where, say, two columns are separated by the same spacing as there is padding around the card.

Separator type

Separator = true | false

V1.0 parser requirements

For v1.0 I've updated the spec that separator is back to being a bool instead of an object. We will add the object back in a future release.

Parsers should parse the bool and populate the Separator object with an IsVisible property.

"separator": true becomes

"separator": {
"isVisible": true,
"thickness": "default",
"color": "default
}

"separator": false becomes

"separator": {
"isVisible": false,
"thickness": "default",
"color": "default
}

HostConfig changes

Removed

• All separation definitions
• HostConfig.strongSeparation property

Currently some HostConfig elements only contain a separation definition. This change removes these separation definitions and therefore these elements would be empty. They will therefore be removed as a result. The elements in question are:

• All input configurations
• columnSet configuration
• column configuration

Added

Spacing definitions at the root level:

spacing: {
    small: number,
    default: number,
    medium: number,
    large: number,
    extraLarge: number,
    padding: number
}

spacing property on actions:

actions: {
    maxActions: number,
    spacing: Spacing,
    buttonSpacing: number,
    showCard: IShowCardActionConfig,
    preExpandSingleShowCardAction?: boolean,    
    actionsOrientation: Enums.Orientation,
    actionAlignment: Enums.ActionAlignment
}

Examples

HostConfig example

var defaultHostConfig: HostConfig.IHostConfig = {
    supportsInteractivity: true,
    spacing: {
        small: 3,
        default: 8,
        medium: 20,
        large: 30,
        extraLarge: 40
    },
    separator: {
        lineThickness: 1,
        lineColor: "#EEEEEE"
    },
    fontFamily: "Segoe UI",
    fontSizes: {
        small: 8,
        normal: 10,
        medium: 12,
        large: 14,
        extraLarge: 16
    },
    fontWeights: {
        lighter: 200,
        normal: 400,
        bolder: 600
    },
    colors: {
        dark: {
            normal: "#0000FF",
            subtle: "#222222"
        },
        light: {
            normal: "#FFFFFF",
            subtle: "#DDDDDD"
        },
        accent: {
            normal: "#0000FF",
            subtle: "#0000DD"
        },
        attention: {
            normal: "#FF6600",
            subtle: "#DD4400"
        },
        good: {
            normal: "#00FF00",
            subtle: "#00DD00"
        },
        warning: {
            normal: "#FF0000",
            subtle: "#DD0000"
        }
    },
    imageSizes: {
        small: 40,
        medium: 80,
        large: 160
    },
    actions: {
        maxActions: 5,
        spacing: "default",
        buttonSpacing: 20,
        showCard: {
            actionMode: "inlineEdgeToEdge",
            inlineTopMargin: 16,
            backgroundColor: "#22000000",
            padding: {
                top: 16,
                right: 16,
                bottom: 16,
                left: 16
            }
        },
        actionsOrientation: "horizontal",
        actionAlignment: "left"
    },
    adaptiveCard: {
        backgroundColor: "#00000000"
    },
    container: {
        normal: {
        },
        emphasis: {
            backgroundColor: "#EEEEEE",
            borderColor: "#AAAAAA",
            borderThickness: {
                top: 1,
                right: 1,
                bottom: 1,
                left: 1
            },
            padding: {
                top: 10,
                right: 10,
                bottom: 10,
                left: 10
            }
        }
    },
    textBlock: {
        color: "dark"
    },
    image: {
        size: "medium"
    },
    imageSet: {
        imageSize: "medium",
        maxImageHeight: 100
    },
    factSet: {
        title: {
            color: "dark",
            size: "normal",
            isSubtle: false,
            weight: "bolder",
            wrap: true,
            maxWidth: 150
        },
        value: {
            color: "dark",
            size: "normal",
            isSubtle: false,
            weight: "normal",
            wrap: true
        },
        spacing: 10
    }
}

Spacing usage examples

{
    "type": "TextBlock",
    "spacing": "none",
    "text": "8a - 12:30p"
}

{
    "type": "TextBlock",
    "spacing": "extraLarge",
    "separator": true,
    "text": "8a - 12:30p"
}

[andrewleader]

Sounds like that might address #136 as you were saying.

[dclaux]

@Anbare Yes, and if you can spare a few minutes, it would be great if you could validate that; I have a pull request with the changes.

[andrewleader]

Definitely, I can try it out once it's in the HTML visualizer, just ping me again when that's live (I've never built the site locally so I'd prefer to use a pre-built version rather than learning how to build the website)

[dclaux]

The thing is I can't really merge it yet - technically this is a "proposed change." Any chance you could pull the code on the finalize-html branch and try the visualizer locally?

[andrewleader]

I might be able to try that tomorrow, probably won't have time today

[matthidinger]

Thanks for typing this one up David, looks great. The v-team reviewed this proposal last week and OK'd it. If anyone sees any red flags please speak up asap

[riarenas]

I think it would be useful to add a checkbox for when the documentation is updated along with the different platform implementation status.

[dclaux]

Good point, done.

[matthidinger]

@bekao raised an interesting question if separator should also be an enum rather than a boolean, so we could add additional separator thickness later one. Potentially, we could just ship with "none" and "medium" . Any thoughts?

[dclaux]

Sounds good to me.

[dclaux]

Who's going to write the spec for this?

[dclaux]

Along the same lines, maybe we should support our various foreground colors for separator. I know of at least one scenario where the separator should be in the accent color. So in the end, the separator property would be specified like this:

"separator": {
    "thickness": "default" | "thick",
    "color": "dark" | "light" | "accent | ...
}

For no separator, just omit the property (or maybe we have a "none" value for thickness.)

[RebeccaAnne]

@dclaux @matthidinger With this change we now have the following in our action config:

spacing: Spacing,
buttonSpacing: number,

Is there a reason we want spacing to be the enum and buttonSpacing to be a number? Seems like we should use the enum for buttonSpacing as well.

[matthidinger]

For v1.0 I've updated the spec that separator is back to being a bool instead of an object. We will add the object back in a future release.

Parsers should parse the bool and populate the Separator object with an IsVisible property.

"separator": true becomes

"separator": {
"isVisible": true,
"thickness": "default",
"color": "default
}

"separator": falsebecomes

"separator": {
"isVisible": false,
"thickness": "default",
"color": "default
}

[robinsedlaczek]

Separators are only rendered in the web view if spacing is set to "large". Will this be changed/fixed when the new spacing model has been completed, or should we create a bug issue?