Merge branch 'main' into deploy

# Conflicts:
#	.github/workflows/azure-static-web-apps-zealous-desert-09e073403.yml

.github/workflows/azure-static-web-apps-zealous-desert-09e073403.yml

@@ -0,0 +1,43 @@
+name: Azure Static Web Apps CI/CD
+
+on:
+ push:
+ branches:
+ - main
+ pull_request:
+ branches: [ "main" ]
+
+jobs:
+ build_and_deploy_job:
+ if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
+ runs-on: ubuntu-latest
+ strategy:
+ matrix:
+ node-version: [20]
+ name: Build and Deploy Job
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ submodules: true
+ - name: Install dependencies
+ run: npm ci
+ - name: Build
+ id: build
+ uses: actions/setup-node@v4
+ with:
+ node-version: ${{ matrix.node-version }}
+ - run: npm run build --if-present
+ - name: Deploy
+ id: deploy
+ if: github.ref == 'refs/heads/main'
+ uses: Azure/static-web-apps-deploy@v1
+ with:
+ azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_ZEALOUS_DESERT_09E073403 }}
+ repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
+ action: "upload"
+ ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
+ # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
+ app_location: "/build" # App source code path
+ api_location: "" # Api source code path - optional
+ output_location: "/" # Built app content directory - optional
+ ###### End of 

.gitignore

@@ -20,3 +20,6 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+.npmrc
+.vs

README.md

@@ -63,7 +63,7 @@ The two suggested workflows are:
 
 ### Requirements
 
-- **Node version 16.14**
+- **Node version >= 18**
 
 ### Setup
 

docs/basics/data/data-binding/data-binding-syntax.md

@@ -16,13 +16,13 @@ The data binding mark-up extension uses the keyword `Binding` in combination wit
 <SomeControl SomeProperty="{Binding Path, Mode=ModeValue, StringFormat=Pattern>
 ```
 
-When there is more than one option parameter, the list is comma-separated.&#x20;
+When there is more than one option parameter, the list is comma-separated.
 
 <table><thead><tr><th width="222">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>Path</code></td><td>The data binding path.</td></tr><tr><td><code>Mode</code></td><td>One of the binding modes, see below.</td></tr><tr><td><code>StringFormat</code></td><td>A pattern showing how the value is to be formatted.</td></tr><tr><td><code>ElementName</code></td><td>Can be shortened by using # in the path.</td></tr><tr><td><code>Converter</code></td><td>A function that converts the value.</td></tr><tr><td><code>RelativeSource</code></td><td>Works on the visual tree instead of the logical tree.</td></tr></tbody></table>
 
 ## Data Binding Path
 
-The first parameter is usually the path to the data source. This is an object in a data context that _Avalonia_ locates when it performs data binding.&#x20;
+The first parameter is usually the path to the data source. This is an object in a data context that _Avalonia_ locates when it performs data binding.
 
 There is no need to use the parameter name `Path`here. So these bindings are equivalent:
 
@@ -56,7 +56,7 @@ You can specify data binding without a path. This binds to the data context of t
 
 You can change how data is moved in a data binding by specifying the data binding mode.
 
-&#x20;
+
 
 <img src={DataBindingModeDiagram} alt=''/>
 
@@ -70,7 +70,7 @@ The available binding modes are:
 
 <table><thead><tr><th width="250">Mode</th><th>Description</th></tr></thead><tbody><tr><td><code>OneWay</code></td><td>Changes in the data source are automatically propagated to the binding target</td></tr><tr><td><code>TwoWay</code></td><td>Changes in the data source are automatically propagated to the binding target, and the other way around as well.</td></tr><tr><td><code>OneTime</code></td><td>The value from the data source is propagated at initialization to the binding target, but subsequent changes are ignored</td></tr><tr><td><code>OneWayToSource</code></td><td>Changes in the binding target are propagated to the data source, but not the other way.</td></tr><tr><td><code>Default</code></td><td>The binding mode is based on a default mode defined in the code for the property. See below.</td></tr></tbody></table>
 
-When no mode is specified, then the default is always used. For a control property that does not change value due to user interaction, the default mode is generally `OneWay`. For a control property that does change value due to user input, then the default mode is usually `TwoWay`.&#x20;
+When no mode is specified, then the default is always used. For a control property that does not change value due to user interaction, the default mode is generally `OneWay`. For a control property that does change value due to user input, then the default mode is usually `TwoWay`.
 
 For example, the default mode for a `TextBlock.Text` property is `OneWay`, and the default mode for a `TextBox.Text` property is `TwoWay`.
 
@@ -117,20 +117,20 @@ Whenever a `StringFormat` parameter is present, the value of the binding will ac
 
 _Avalonia_ has a range of built-in data binding converters. These include:
 
-* a string formatting converter&#x20;
+* a string formatting converter
 * null testing converters
 * Boolean operation converters
 
 :::info
-For full information on Avalonia built-in data binding converters, see the reference [here](../../../reference/built-in-data-binding-converters.md).&#x20;
+For full information on Avalonia built-in data binding converters, see the reference [here](../../../reference/built-in-data-binding-converters.md).
 :::
 
 ### Custom Conversions
 
-If none of the built-in converters are meet your requirements, then you can implement a custom converter.&#x20;
+If none of the built-in converters are meet your requirements, then you can implement a custom converter.
 
 :::info
-An example of a custom converter can bind an image file. For guidance on how to create a custom converter for an image, see [here](../../../guides/data-binding/how-to-bind-image-files.md).&#x20;
+An example of a custom converter can bind an image file. For guidance on how to create a custom converter for an image, see [here](../../../guides/data-binding/how-to-bind-image-files.md).
 :::
 
-&#x20;
+

docs/basics/data/data-binding/data-context.md

@@ -13,9 +13,9 @@ When Avalonia performs data binding, it has to locate an application object to b
 
 <img src={DataContextBindingOverviewDiagram} alt=''/>
 
-Every control in Avalonia has a property called `DataContext`, and this includes built-in controls, user controls and windows.&#x20;
+Every control in Avalonia has a property called `DataContext`, and this includes built-in controls, user controls and windows.
 
-When binding, Avalonia performs a hierarchical search of the logical control tree, starting with the control where the binding is defined, until it finds a data context to use.&#x20;
+When binding, Avalonia performs a hierarchical search of the logical control tree, starting with the control where the binding is defined, until it finds a data context to use.
 
 <img src={DataContextTreeSearchDiagram} alt=''/>
 

docs/basics/data/data-binding/index.md

@@ -6,11 +6,11 @@ import DataBindingBasicOverviewDiagram from '/img/gitbook-import/assets/image (3
 
 # Data Binding
 
-Avalonia uses data binding to move data from application objects into UI controls, change the data in application objects in response to user input, and initiate actions on the application objects in response to commands from the user.  
+Avalonia uses data binding to move data from application objects into UI controls, change the data in application objects in response to user input, and initiate actions on the application objects in response to commands from the user. 
 
 <img src={DataBindingBasicOverviewDiagram} alt=''/>
 
-In this arrangement, the control is the **binding target**, and the object is the **data source**.&#x20;
+In this arrangement, the control is the **binding target**, and the object is the **data source**.
 
 Avalonia runs a data binding system to complete much of the above activity from simple mappings declared in the XAML; that is without requiring you to add a lot of additional coding.
 
@@ -34,10 +34,10 @@ Bindings can be unidirectional: where changes in the properties of a bound appli
 <TextBlock Text="{Binding StatusMessage}" />
 ```
 
-Binding is used with the MVVM architectural pattern, and this is one of the principle ways of programming with Avalonia UI.&#x20;
+Binding is used with the MVVM architectural pattern, and this is one of the principle ways of programming with Avalonia UI.
 
 :::info
-For more information about how to use the MVVM Pattern with Avalonia, see the concept page [here](../../../concepts/the-mvvm-pattern).&#x20;
+For more information about how to use the MVVM Pattern with Avalonia, see the concept page [here](../../../concepts/the-mvvm-pattern).
 :::
 
 :::info

docs/basics/index.md

@@ -7,9 +7,7 @@ title: Basics
 
 This section will introduce you to the basic concepts required to build an application with Avalonia.
 
-```mdx-code-block
 import {DocsCardList} from '../../src/components/DocsCard';
 import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 
 <DocsCardList list={useCurrentSidebarCategory().items} />
-```

docs/basics/user-interface/animations.md

@@ -14,7 +14,7 @@ There are two types of animations in _Avalonia UI_:
 
 ## Keyframe Animation
 
-The simplest keyframe animation will change one property value over a a specified duration by defining two keyframes with cue points at the start (0% of the duration) and the end (100% of the duration). 
+The simplest keyframe animation will change one property value over a a specified duration by defining two keyframes with cue points at the start (0% of the duration) and the end (100% of the duration).
 
 <img src={AnimationKeyframeDiagram} alt=''/>
 

docs/basics/user-interface/controls/creating-controls/index.md

@@ -5,9 +5,7 @@ title: Creating Controls
 
 # Creating Controls
 
-```mdx-code-block
 import {DocsCardList} from '../../../../../src/components/DocsCard';
 import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 
 <DocsCardList list={useCurrentSidebarCategory().items} />
-```

docs/basics/user-interface/controls/index.md

@@ -28,6 +28,69 @@ To get started with using controls in Avalonia UI, you can refer to the document
 
 By exploring these resources, you'll gain a solid foundation in using controls within Avalonia UI and be able to create rich and interactive user interfaces for your applications.
 
+## Types of Builtin Controls
+
+_Avalonia UI_'s builtin controls can be loosely classified into the below types:
+
+* Drawn Controls
+* Layout Controls
+* User Controls*
+* Templated Controls
+ * Fully Customizable
+ * Partially Customizable
+
+*User controls are only available for apps.
+
+:::note
+These classifications are somewhat related to the discussion in [Choosing A Custom Control Type](creating-controls/choosing-a-custom-control-type).
+:::
+
+### Drawn Controls
+
+Drawn controls are those that are responsible for generating their own geometry or bitmaps and rendering themselves. Examples of these controls include `Border`, `TextBlock` and `Image`. Drawn controls are the foundational controls used to construct everything else.
+
+Most drawn controls have standard properties that can be used to adjust their appearance and size but they do not allow re-templating. This means as an app developer you can’t change the functionality or style of these controls without dropping into C#, deriving a new version of the control and intercepting the rendering methods.
+
+### Layout Controls
+
+Layout controls are special in that they have no appearance by themselves. Layout controls like `Grid`, `StackPanel` and others are responsible for defining the layout of their children and behave as a parent container. The child controls are responsible for rendering the UI while the layout parent control simply sets size and position (which have no appearance by themselves).
+
+It is not very common for app developers to modify framework provided layout controls.
+
+:::note
+Some layout controls like `Grid` have properties such as `Background` to simplify common use cases. Using these properties does give some appearance to these controls.
+:::
+
+## User Controls
+
+_Avalonia UI_ never provides `UserControl`s by itself as these are not considered general-purpose. For more information on creating and using `UserControl`s in your app see [Choosing A Custom Control Type](creating-controls/choosing-a-custom-control-type).
+
+### Templated Controls
+
+Most standard controls in _Avalonia UI_ are templated controls which means their visual appearance is defined in a XAML control template separated from functionality. It is the foundation for the concept of lookless controls that originated in WPF.
+
+Application developers can change the XAML template of a templated control and make it appear completely differently. This functionality is not available in all UI frameworks and is one of the most powerful features of XAML-based UI frameworks.
+
+:::note
+Re-templating controls is a last-resort for app developers. It also means you will be responsible for keeping the template updated with any changes upstream. Instead, it is better to:
+
+ 1. Attempt to use existing properties to customize the control
+ 2. Create a new style with _Avalonia UI_'s extremely powerful style selectors to modify what you need in the existing template
+ 3. As a last resort, re-template
+:::
+
+#### Fully Customizable
+
+The majority of templated controls in _Avalonia UI_ are fully customizable. This means it is possible to completely replace the control’s template and change its appearance. The `Button` control is a good example but all templated controls in _Avalonia UI_ try to be fully customizable by default. With a fully customizable templated control the app has near total ability to style or change everything you see drawn in the UI.
+
+#### Partially Customizable
+
+In practice, having fully replaceable control templates is not always possible. There is a spectrum in control design between supporting common use-cases easily and making the control fully re-templatable. For high-complexity controls like the `DataGrid` the spectrum shifts towards supporting the intended use cases and the control cannot, and should not, be fully re-templated. These controls also usually have a very high number of template parts (required control elements that are used directly by the C# implementation of the control).
+
+In the case of a `DataGrid` it is still possible to re-template individual components or parts of the control. It is just extremely difficult to completely change how it looks and functions.
+
+Partially customizable templated controls on the order of `DataGrid` are rare as first-party controls provided by the framework itself.
+
 ## Creating Controls
 
-In Avalonia, you have the flexibility to create custom controls tailored to your application's specific requirements. See the [Creating Controls](creating-controls) section for more information
+In Avalonia, you have the flexibility to create custom controls of all types tailored to your application's specific requirements. See the [Creating Controls](creating-controls) section for more information