Push live

AdaptiveCards/authoring-cards/speech.md

@@ -13,7 +13,7 @@ The `speak` tag enables the adaptive card to be delivered to an environment wher
 
 ## Speak property
 To support speech we have a `speak` property which contains text to say to the user. The text can be annotated using speech synthesis markup language
-([SSML](https://msdn.microsoft.com/library/office/hh361578)). SSML controls the speed, tone, and inflection of the speech.  It even allows you to stream audio or a render a TTS audio stream from your own service, giving you a great deal of flexibility for customization.
+([SSML](/previous-versions/office/developer/speech-technologies/hh361578(v=office.14))). SSML controls the speed, tone, and inflection of the speech.  It even allows you to stream audio or a render a TTS audio stream from your own service, giving you a great deal of flexibility for customization.
 
 There are two patterns for speak property usage by a host application:
 
@@ -32,4 +32,4 @@ There are two patterns for speak property usage by a host application:
 
 ## Speech content design
 
-Content designed for speech is different from content designed for visual display. When you design a card, you are designing an entire visual experience to present information to a user in a way that delights them. When designing for speech, you should think about how to verbally describe the content in a way that delights the user.  
+Content designed for speech is different from content designed for visual display. When you design a card, you are designing an entire visual experience to present information to a user in a way that delights them. When designing for speech, you should think about how to verbally describe the content in a way that delights the user.

AdaptiveCards/getting-started/bots.md

@@ -110,8 +110,8 @@ If your bot is developed using .NET or NodeJS we have libraries to make building
 
 Platform|Install|Learn more
 --------|-------|----------
-.NET | `Install-Package AdaptiveCards -IncludePrerelease` | [Bot Framework .NET Docs](https://docs.microsoft.com/bot-framework/dotnet/bot-builder-dotnet-add-rich-card-attachments)
-NodeJS | `npm install adaptivecards` | [Bot Framework NodeJS Docs](https://docs.microsoft.com/bot-framework/nodejs/bot-builder-nodejs-send-rich-cards)
+.NET | `Install-Package AdaptiveCards -IncludePrerelease` | [Bot Framework .NET Docs](/bot-framework/dotnet/bot-builder-dotnet-add-rich-card-attachments)
+NodeJS | `npm install adaptivecards` | [Bot Framework NodeJS Docs](/bot-framework/nodejs/bot-builder-nodejs-send-rich-cards)
 
 
 ## Channel status
@@ -126,4 +126,4 @@ We've just scratched the surface in this tutorial, so please take a look at the
 * [Browse Sample cards](https://adaptivecards.io/samples/) for inspiration
 * Use the [Schema Explorer](https://adaptivecards.io/explorer) to learn the available elements
 * Build a card using the [Interactive Visualizer](https://adaptivecards.io/visualizer/index.html?hostApp=Skype)
-* [Get in touch](https://adaptivecards.io/connect) with any feedback you have
+* [Get in touch](https://adaptivecards.io/connect) with any feedback you have

AdaptiveCards/getting-started/windows.md

@@ -16,7 +16,7 @@ The first Windows experience to supports Adaptive Cards is Timeline, a brand new
 
 ### UserActivity API
 
-The [`Windows.ApplicationModel.UserActivities.UserActivity`](https://docs.microsoft.com/uwp/api/windows.applicationmodel.useractivities.useractivity) API is what populates an Activity into Timeline.
+The [`Windows.ApplicationModel.UserActivities.UserActivity`](/uwp/api/windows.applicationmodel.useractivities.useractivity) API is what populates an Activity into Timeline.
 
 The Adaptive Card will be supplied via the `Content` property of `VisualElement`, as seen below:
 
@@ -32,7 +32,7 @@ await userActivity.SaveAsync();
 
 There is a great 45-min learn module that covers these steps end-to-end.
 
-[Integrate adaptive cards into Windows 10 Timeline](https://docs.microsoft.com/learn/modules/integrate-app-into-windows-10-timeline/)
+[Integrate adaptive cards into Windows 10 Timeline](/learn/modules/integrate-app-into-windows-10-timeline/)
 
 ### Learn more
 
@@ -50,4 +50,4 @@ We've barely scratched the surface in this tutorial, so check back soon and brow
 * [Browse Sample cards](https://adaptivecards.io/samples/) for inspiration
 * Use the [Schema Explorer](https://adaptivecards.io/explorer) to learn the available elements
 * Build a card using the [Interactive Visualizer](https://adaptivecards.io/visualizer/index.html?hostApp=Skype)
-* [Get in touch](https://adaptivecards.io/connect) with any feedback you have
+* [Get in touch](https://adaptivecards.io/connect) with any feedback you have

AdaptiveCards/rendering-cards/actions.md

@@ -12,4 +12,5 @@ By default, the actions will render as buttons on the card, but it's up to your
 
 * **Action.OpenUrl** - open the specified `url`.  
 * **Action.Submit** - take the result of the submit and send it to the source. How you send it to the source of the card is entirely up to you.
-* **Action.ShowCard** - invokes a dialog and renders the sub-card into that dialog. Note that you only need to handle this if `ShowCardActionMode` is set to `popup`.
+* **Action.ShowCard** - invokes a dialog and renders the sub-card into that dialog. Note that you only need to handle this if `ShowCardActionMode` is set to `popup`.
+* **Action.ToggleVisibility** - shows or hides one or more elements in the card.

AdaptiveCards/rendering-cards/renderer-behaviour.md

@@ -0,0 +1,212 @@
+---
+title: Renderer Behaviour Guideline
+author: manujai
+---
+
+
+# Adaptive Card Renderer Behaviour Guideline
+
+The following specification describes the design guideline to be followed when implementing the behaviour of a renderer with respect to parsing the relationship between the card elements. 
+> [!IMPORTANT]
+> 
+> This content is not finished yet. Check back shortly.
+
+
+## Behaviours 
+
+The Renderer **MUST** take care to the following behaviours when rendering card elements with respect to the attributes mentioned in this doc. 
+
+1. **Constraints**
+2. **Image Size**
+3. **Action.Submit**
+
+## Constraints
+
+The renderer should manage **Constraints** taking into account the various factors such as margin, padding, height and width etc configuration of the card elements and its children.
+
+## Width 
+
+1. Allowed values - `auto`, `stretch` and fixed values in terms of `pixels` and `weight`
+2. `auto` provides sufficient space for expansion of width (supports min expansion)
+3. `stretch` takes up the remaining width (supports max expansion)
+
+Below below scenarios describes how the constraints are affected with different width combinations for columns
+
+### `auto` vs `stretch`
+1. Columns with `auto` and `stretch` width.
+
+![Column with auto and stretch width](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/width_1_auto_stretch.png)
+
+* The first column with `auto` width takes sufficient space to display the content and the second column with `stretch` width takes up the entire space.
+
+2. Columns with only `stretch` width
+
+![Column with only stretch width](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/width_2_stretch_stretch.png)
+
+* Columns with only stretch width takes up the remaining spaces after dividing it equally.
+
+3. `auto`,`stretch` and `auto` 
+
+![Column with auto and stretch combination width](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/width3_auto_stretch_auto.png)
+
+The **first** and **third** columns width is adjusted first to accommodate the elements sufficiently and the **second** column with stretched width takes up the remaining space. 
+
+4. Order of displaying elements with `auto` width columns
+
+![Columns with auto width](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/width6_all_auto.png)
+
+* Columns with `auto` will position themselves to provide ample space for the content to render. 
+* In case of **Image views**, images will downscale to fit the remaining width. 
+* **Note:** Images will downscale only for `stretch` and `auto` image size, but not for fixed width and height in pixels.    
+
+### `weights` vs `pixels`
+
+1. Columns with `weight` and `pixel` width combination
+
+![Columns with weightage and pixel width combination](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/width_4_w50_p100_w50.png)
+
+* The above card has three columns with the following width configuration - 
+* `Column1: Weight 50`, `Column2: 100px`, `Column3: Weight 50`
+* The width of Column 2 is determined by the `pixel value`
+* The width of Column 1 and 3 is adjusted based on the `weights` and the calculated `weight ratio`.
+
+2. Columns with `weight`, `pixel width` and `auto` attributes
+
+![Columns with wight, pixel width and auto combination](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/width5_w50_p100_w50_auto.png)
+
+* The above card has four columns with the following width configuration - 
+* `Column1: Weight 50`, `Column2: 100px`, `Column3: Weight 50`, and `Column4: auto`
+* **Note:** Image view with `auto` width column downscales to adjust to the remaining space. 
+
+### Precedence order of displaying elements with the width attribute
+`px` > `weight` > `auto` > `stretch`
+
+
+## Height 
+
+ Allowed values - `auto` and `stretch` 
+
+Below  scenarios describes how the constraints are affected with different height combinations for card elements
+
+1. Elements expand freely vertically when card is not of fixed height
+
+![Columns with auto and stretch height](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/height1_text_wrap_off.png)
+
+* Both the columns can expand sufficiently vertically irrespective of `auto` and `stretch` values
+* This is with the `wrap` property disabled for the text block.
+
+2. The card below has the `wrap` property enabled for the text block. 
+
+![Column with wrap property for text block](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/height2_text_wrap_on.png)
+
+
+## Spacing and Separator
+
+ 1. **Spacing** - Allowed values `none`, `small`, `default`, `medium`, `large`, `extra large` and `padding` 
+
+* Spacing attribute adds spacing between this element and the preceding element.
+
+![Elements with different spacing combination](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/spacing1.png)
+
+* Spacing attribute does not have any effect when its the first element in the view container. 
+
+![Element where spacing has no effect](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/spacing_no_effect.png)
+
+* The elements marked with arrow are the first elements among its siblings, so spacing has no effect. 
+
+ 2. **Separator** - Possible values (on/off toggle)
+
+* Draws a seperating line at the top of the element.
+
+![Elements with seperator attribute](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/spacing3_seperator.png)
+
+3. **Spacing and Seperator combination**
+
+* The constraints of the spacing and the seperator combination are illustrated below. 
+
+![Spacing and seperator combination](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/spacing4_with_seperator.png)
+
+* The overall spacing distance is maintained with respect to the values provided.
+* The seperator is added halfway in the middle of the spaced distance.
+
+[Note. Need to confirm the distance where the seperator is inserted in the spacing area. Seems like the middle]
+
+## Container Styles
+
+* Provides styling hints for containers such as columns and columnset
+* Allowed values `none`, `default`, `emphasis`, `good`, `attention`, `warning` and `accent`
+* These predefined style options provides padding for the elements within the container and background color
+
+
+![Columns and ColumnSet Style Combination](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/style1.png)
+
+1. Card A illustrates columns and columnset with no style options
+2. Card B illustrates columnset with **Attention** style. Notice the padding within the columnset container and the change in background color. 
+3. Card C illustrates columns with styling only. Similar to the previous one, column includes padding and background change. 
+4. Card D illustrates columns and columnset both with style options.
+
+[Note. Need to check how the padding amount is determined. Is it determined by the host? ]
+
+## Bleed
+
+* This property allows the container such as columns and columnset to bleed through its parent. 
+* Possible values `on` and `off`.
+
+
+![Column with bleed property](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/style2_withBleed.png)
+
+1. Card A illustrates columns and columnset with regular styling.
+2. Card B illustrates the first column with bleed option. The content just bleeds through its boundaries to its parent's. 
+
+## Image Size
+
+### `Size` attribute
+* Allowed values - `auto`, `stretch`, `small`, `medium`, `large`
+* `auto` : Images will scale down to fit if needed, but will not scale up to fill the area.
+* `stretch` : Image with both scale down and up to fit as needed.
+* `small`, `medium` and `large`: Image is displayed with a fixed width, where the width is determined by the host.
+
+1. `auto` vs `stretch`
+
+![Image with auto and stretch behaviour](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/image_size_auto_stretch.png)
+
+2. Column width and Image Size combination
+
+![Column width and image size combination](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/imagesize2.png)
+
+* Generally, Columns with `stretch` width allow images to upscale freely with `stretch` size.
+* Columns with `auto` width allows image to occupy exact space irrespective of `auto` and `stretch` size of image.
+* Column width takes more precedence in determining the image size in this arrangement.
+
+### Image `Width (in pixels)` attribute
+* This provides the desired on-screen width of the image. 
+* `size` property is overriden when a value is specified
+
+![Column width and image width in pixels combination](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/image_size_3.png)
+* The column with `auto` width will have more precedence than `stretch` in providing room for image content in this arrangement. 
+
+### Column Width (weight and pixel) and Image size (auto and stretch) Combination
+
+![Column width and image size combination](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/column_width_image_width_2.png)
+* Images with `auto` size takes sufficient space for expansion (or downscales) within the column constraints of `weight` and `pixel` width. 
+* Images with `stretch` size can expand to fill the remaining space within the constraints of column `weight` and `pixel` width. 
+
+## Action.Submit
+* `Action.Submit` element gathers input fields, merges with optional data field, and sends an event to the client.
+* A significant difference in the element behaviour is present between 1.x and 2.x version of the ACL renderer.
+
+![Column width and image width combination](https://github.com/manujai/AdaptiveCards/blob/doc_renderer_behaviour/AdaptiveCards/content/action_submit_behaviour.png)
+
+* `1.x Renderer` - The inputs are collected from all fields irrespective of the where in the hierarchy the input field is present. 
+* `2.x Renderer` - The inputs are collected from fields present in parent container or as a sibling of the `Action.Submit` element. 
+
+## Summary
+* Column width takes more precedence in determining the size of the image than its image size (auto, stretch, min width etc). 
+* The precedence of the column width taken to display its content sufficiently - `px` > `weight` > `auto` > `stretch`
+* Image `size` (auto, stretch) is **ignored** when Image `width` and `height` in px is provided. 
+* Image `stretch` size attribute will upscale the image only when there is remaining space and column auto is **not** `auto`.
+* An image stretches itself to the limit where it maintain its aspect ratio in the space available in the column. In turn, the height expands freely.
+* `Spacing` attribute will not have any effect when its the first or the only element among its sibling. 
+
+
+

AdaptiveCards/rendering-cards/speech.md

@@ -10,12 +10,11 @@ ms.topic: article
 
 To support speech adaptive Cards has the `speak` property which contains information on how a card should be read aloud to a user.
 
-The speech tag can be annotated using  [SSML markup](https://msdn.microsoft.com/library/office/hh361578(v=office.14).aspx). 
+The speech tag can be annotated using  [SSML markup](/previous-versions/office/developer/speech-technologies/hh361578(v=office.14)). 
 SSML gives you the ability control the speed, tone, inflection of the speech.  It even allows you to stream audio or a render a TTS audio stream
 from your own service, giving you a great deal of customization.
 
 There are 2 patterns for speak property usage by a host application:
 * **on delivery** - When a card is delivered a client may opt to read the Speak property for the card to describe the card as a whole.
 * **on demand** - In order to support a richer accessibility model the schema supports a speak tag per element.  
-This allows for clients to read each element to recipients with accessibility requirements.
-
+This allows for clients to read each element to recipients with accessibility requirements.