Merge branch 'main' into users/makinc/temperature-units

CONTRIBUTING.md

@@ -51,7 +51,7 @@ This repository uses the following tooling. See below for more info.
 1. Write a spec describing the API and behavior of the component. See instructions for [component specs](/specs/README.md).
 2. Ensure UX specs are up to date and tokens are generated. See instructions for [contributing to Nimble Tokens](/packages/nimble-tokens/CONTRIBUTING.md).
 3. Expose any tokens in the token provider and add web component logic. See instructions for [contributing to Nimble Components](/packages/nimble-components/CONTRIBUTING.md).
-4. Add wrappers for each framework. See instructions for [adding Angular wrappers](/packages/angular-workspace/nimble-angular/CONTRIBUTING.md). See instructions for [adding Blazor wrappers](/packages/nimble-blazor/CONTRIBUTING.md).
+4. Add wrappers for each framework. See instructions for [adding Angular wrappers](/packages/angular-workspace/nimble-angular/CONTRIBUTING.md). See instructions for [adding Blazor wrappers](/packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md).
 5. Publish and use! 🎉
 
 ## Documentation policies

change/@ni-nimble-blazor-a9914c9f-4ea3-473f-b8a9-372855b20c2c.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Update Blazor docs for Spright and workspace change",
+  "packageName": "@ni/nimble-blazor",
+  "email": "7282195+m-akinc@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}

change/@ni-nimble-components-77f57124-12c0-45f1-b1e7-69f211fc2e7b.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Update Blazor docs for Spright and workspace change",
+  "packageName": "@ni/nimble-components",
+  "email": "7282195+m-akinc@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}

change/@ni-nimble-tokens-e091ea87-cc71-4f0c-9a76-45ef350779a8.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Update Blazor docs for Spright and workspace change",
+  "packageName": "@ni/nimble-tokens",
+  "email": "7282195+m-akinc@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}

change/@ni-spright-blazor-aecd2f90-e8d3-4a09-96c2-c5db85ec2d13.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Update Blazor docs for Spright and workspace change",
+  "packageName": "@ni/spright-blazor",
+  "email": "7282195+m-akinc@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}

packages/blazor-workspace/CONTRIBUTING.md → packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md

@@ -121,13 +121,13 @@ When creating a new project in the Blazor workspace, ensure it includes the foll
 ### Enabling IIS
 
 Click Start, open "Turn Windows features on or off", and configure "Web Management Tools" and "World Wide Web Services" in the following way:
-![IIS Feature Configuration](/packages/nimble-blazor/docs/WindowsFeatures-IIS.jpg)
+![IIS Feature Configuration](/packages/blazor-workspace/docs/WindowsFeatures-IIS.jpg)
 ### Running published output
 
 The commandline build will create a published distribution of the Blazor client example app, which can also be tested via IIS:
 - Open Internet Information Services (IIS) Manager
 - In the left pane, right click "Sites" and click "Add Website..."
 - Pick a site name
-- Under "Physical Path", click [...] and browse to your `nimble-blazor\dist\blazor-client-app` directory
+- Under "Physical Path", click [...] and browse to your `blazor-workspace\dist\blazor-client-app` directory
 - Under "Binding", pick a port other than 80 (such as 8080), then click "OK"
 - Open http://localhost:8080 (or whatever port you chose)

packages/blazor-workspace/NimbleBlazor/NimbleBlazor.csproj

@@ -6,6 +6,7 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <DebugType>embedded</DebugType>
     <Authors>NI</Authors>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageProjectUrl>https://github.com/ni/nimble</PackageProjectUrl>
     <RepositoryUrl>https://github.com/ni/nimble</RepositoryUrl>
     <RepositoryType>git</RepositoryType>
@@ -57,6 +58,7 @@
   <ItemGroup>
     <None Include="package.json" />
     <None Include="packages.lock.json" />
+    <None Include="README.md" Pack="true" PackagePath="\"/>
   </ItemGroup>
 
   <Target Name="CopyNimbleResources" BeforeTargets="BeforeBuild">

packages/blazor-workspace/NimbleBlazor/README.md

@@ -0,0 +1,150 @@
+# Nimble Blazor
+
+[![Nimble Nuget Version](https://img.shields.io/nuget/v/NimbleBlazor.svg)](https://www.nuget.org/packages/NimbleBlazor)
+
+## Getting Started
+
+### Prerequisites
+
+1. IDE:
+    - **Windows with Visual Studio**: For Blazor development on Windows, the suggested IDE is:
+        - Visual Studio 2022 ([Enterprise, if available](https://my.visualstudio.com/Downloads?PId=8229)): Choose the "ASP.NET and Web Development" Workload in the installer
+        - Ensure Visual Studio is completely up to date (v17.1.6+): In Visual Studio click "Help" then "Check for Updates"
+    - **Mac with Visual Studio Code**: Install [Visual Studio Code](https://code.visualstudio.com/) and open it. Open the Extensions pane ("Preferences" >> "Extensions"), and search for / install the `ms-dotnettools.csharp` extension.
+2. .NET SDK: See [the main contributing doc](/CONTRIBUTING.md) for the required version.
+
+### Creating a new Blazor project
+
+The built-in Blazor template projects are good starting points. First, decide whether to create a Blazor Server or Blazor Client/WebAssembly application (see the [Blazor hosting model documentation](https://docs.microsoft.com/en-us/aspnet/core/blazor/hosting-models?view=aspnetcore-6.0) for more information on both models).
+
+**Visual Studio**: Choose "New" >> "Project", and pick "Blazor Server app" or "Blazor WebAssembly app".  
+**VS Code**: Create a new folder, then open it in VS Code. Choose "View" >> "Terminal", and type `dotnet new blazorserver -f net6.0` (for Blazor Server) or `dotnet new blazorwasm -f net6.0` (for Blazor WebAssembly) and press Enter. Open the Command Palette ("View" >> "Command Palette" or Ctrl-Shift-P), enter ".NET Generate Assets for Build and Debug" and press Enter.
+
+Additional Resources: [Microsoft tutorial: Build a web app with Blazor](https://docs.microsoft.com/en-us/learn/modules/build-blazor-webassembly-visual-studio-code/); [`dotnet new` documentation](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-new)
+
+### Reference NimbleBlazor in a Blazor project
+
+1. Add a PackageReference to the NimbleBlazor NuGet package:
+    - Using the published NimbleBlazor NuGet package (recommended)
+        - Visual Studio: "Project" >> "Manage NuGet Packages", pick "nuget.org" in the "Package Source" dropdown, and ensure "Include prerelease" is checked. Search for "NimbleBlazor", select it and click the "Install" button.
+        - VS Code: Run the command `dotnet add package NimbleBlazor --source https://api.nuget.org/v3/index.json --prerelease` in the Terminal window.
+    - For Nimble developers, with a locally built NimbleBlazor NuGet (built from the Nimble repo):
+        - Run `npm run build`, and then `npm run pack -w @ni/nimble-blazor` from the root of the Nimble repo
+        - Visual Studio: "Project" >> "Manage NuGet Packages". Click the gear/Settings button. Add a new Package Source ("NimbleBlazor") as `[NimbleRepoDirectory]\packages\blazor-workspace\dist` and commit/ close Settings. Pick "NimbleBlazor" in the "Package Source" dropdown, and ensure "Include prerelease" is checked. Search for "NimbleBlazor", select it and click the "Install" button.
+        - VS Code: Run the command `dotnet add package NimbleBlazor --source [NimbleRepoDirectory]\packages\blazor-workspace\dist` in the Terminal window.
+2. Add required references to Blazor code
+    - Open `_Imports.razor`, and add a new line at the bottom: `@using NimbleBlazor`
+    - Open `_Layout.cshtml` (BlazorServer) / `wwwroot/index.html` (Blazor WebAssembly).  
+    At the bottom of the `<head>` section (right before `</head>`), add  
+        ```html
+        <link href="_content/NimbleBlazor/nimble-tokens/css/fonts.css" rel="stylesheet" />
+        ```  
+        At the bottom of the `<body>` section (right before `</body>`), add  
+        ```html
+        <script src="_content/NimbleBlazor/nimble-components/all-components-bundle.min.js"></script>
+        ```  
+
+Additional Resources: [`dotnet add package` documentation](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-add-package)
+
+### Use Nimble Blazor components
+
+For a simple modification to the Blazor template project: open `Index.razor` and add the following code at the bottom, to add a Nimble text field that updates when a Nimble button is clicked:
+```cs
+<NimbleTextField Value="@ButtonClickStatus"></NimbleTextField>
+<NimbleButton Appearance="ButtonAppearance.Outline" @onclick="OnButtonClicked">Click Me</NimbleButton>
+@code {
+    protected string ButtonClickStatus { get; set; } = string.Empty;
+    private int _buttonClickCount = 0;
+
+    private void OnButtonClicked(MouseEventArgs args)
+    {
+        _buttonClickCount++;
+        ButtonClickStatus = $"Button Clicked {_buttonClickCount} times";
+    }
+}
+```
+
+To test out your changes, do "Debug" >> "Start without Debugging" in Visual Studio, or `dotnet watch run` in the VS Code Terminal.
+
+More complete examples can be found in the Demo.Client/Server example projects.
+
+#### NimbleTable usage
+
+The `NimbleTable` requires that its data be set via the `SetDataAsync` method. The appropriate place to call this method is either in the `OnAfterRenderAsync` override of the hosting component or after that method has been called for the first time.
+
+As the `NimbleTable` is generic a client must supply its generic type in the markup using the `TData` property syntax. The following code represents a typical usage of the `NimbleTable`:
+```html
+<NimbleTable TData="MyRecordType" @ref="_table">
+@code {
+    private NimbleTable<MyRecordType>? _table;
+    private IEnumerable<MyRecordType> TableData { get; set; } = Enumerable.Empty<MyRecordType>();
+    ...
+    public override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        await base.OnAfterRenderAsync(firstRender);
+        await _table.SetDataAsync(TableData); // populate TableData before here
+    }
+
+    public class MyRecordType
+    {
+        ...
+    }
+}
+```
+
+For more information regarding the Blazor component lifecycle mechanisms (such as `OnAfterRenderAsync`), please consult the [Microsoft Blazor docs](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/lifecycle).
+
+### Theming and Design Tokens
+
+To use Nimble's theme-aware design tokens in a Blazor app, you should have a `<NimbleThemeProvider>` element as an ancestor to all of the Nimble components you use. The app's default layout (`MainLayout.razor` in the examples) is a good place to put the theme provider (as the root content of the page).
+
+#### Using Nimble Design Tokens (CSS/SCSS)
+
+Blazor doesn't have built-in support for using/ building SCSS files, however Nimble's design tokens can be used as CSS variables (`var(--ni-nimble-...)`) in Blazor apps without any additional work.  
+For a full list of supported variable names, see the [Nimble Storybook, "Tokens" >> "Theme-aware tokens"](https://nimble.ni.dev/storybook/?path=/story/tokens-theme-aware-tokens--theme-aware-tokens&args=propertyFormat:CSS).
+
+**Experimental: Manually including Nimble Tokens SCSS files**  
+There are currently extra manual steps required to use the Nimble design tokens as SCSS in Blazor projects (which results in better IntelliSense and compile-time checking for the Nimble tokens and variables):
+1. Copy the Nimble tokens SCSS files into your Blazor project: Include `tokens.scss` and `tokens-internal.scss` from the `nimble-components` in your Blazor project directory. The simplest way to get these files is via `unpkg.com` (latest versions: [tokens.scss](https://unpkg.com/@ni/nimble-components/dist/tokens-internal.scss), [tokens-internal.scss](https://unpkg.com/@ni/nimble-components/dist/tokens-internal.scss))
+2. In `tokens.scss`, add a file extension to the `@import` statement at the top (`'./tokens-internal'` => `'./tokens-internal.scss'`)
+3. Add a NuGet package reference to a SASS/SCSS compiler to your Blazor project. Both [LibSassBuilder](https://www.nuget.org/packages/LibSassBuilder) and [DartSassBuilder (latest/prerelease)](https://www.nuget.org/packages/DartSassBuilder) have been tested with Blazor projects and work with no additional configuration required.
+4. Add new SCSS files for your Razor components (e.g. `MyComponent.razor.scss`), and `@import 'tokens.scss'` in it (updating the import relative path as needed).
+5. Use the `$ni-nimble-...` variables in your Blazor application SCSS.
+
+The SCSS compilation happens before the rest of Blazor's compilation, so this approach works fine with Blazor CSS isolation.  
+Note: This approach requires periodically updating the Nimble tokens SCSS files manually (whenever the Nimble Blazor NuGet version is updated).
+
+### Localization (Optional)
+
+Most user-visible strings displayed by Nimble components are provided by the client application and are expected to be localized by the application if necessary. However, some strings are built into Nimble components and are provided only in English.
+
+To provide localized strings in a localized Blazor app:
+1. Add the label providers as children of your `<NimbleThemeProvider>`:
+    - `<NimbleLabelProviderCore>`: Used for labels for all components besides the table
+    - `<NimbleLabelProviderTable>`: Used for labels for the table (and table sub-components / column types)
+2. For each Nimble-provided label shown in the [Label Provider Storybook documentation](https://nimble.ni.dev/storybook/?path=/docs/tokens-label-providers--docs):
+    - Add a new entry for the label in a resource file (`.resx`). You can either add to an existing resx file, or create a new one just for the Nimble strings. The resource value should be the Nimble-provided English default string shown in Storybook.
+    - Follow [standard Blazor localization patterns](https://learn.microsoft.com/en-us/aspnet/core/blazor/globalization-localization) to localize the strings, and load the localized versions at runtime in your application.
+    - Provide Nimble the localized strings with the label provider APIs. For example, to provide the `popupDismiss` label on `NimbleLabelProviderCore`, if you load your string resources with a .NET `IStringLocalizer` instance, your label provider may look like the following:
+        ```xml
+        <NimbleLabelProviderCore PopupDismiss="@LabelStringLocalizer["popupDismiss"]"></NimbleLabelProviderCore>
+        ```
+
+### Using Nimble Blazor in a Blazor Hybrid app
+
+There is currently an [issue in ASP.NET Core](https://github.com/dotnet/aspnetcore/issues/42349) that prevents the necessary JavaScript that Nimble Blazor relies on from loading in a Blazor Hybrid application. The Demo.Hybrid project illustrates the current required steps for getting Nimble Blazor to work properly. This simply involves adding the script `NimbleBlazor.HybridWorkaround.js` in the `index.html` file in `wwwroot`:
+
+wwwroot/index.html
+```html
+    ...
+    <script src="_framework/blazor.webview.js"></script>
+    <script src="_content/NimbleBlazor/nimble-components/all-components-bundle.min.js"></script>
+    <!-- This script is a workaround needed for Nimble Blazor to work in Blazor Hybrid.
+         See https://github.com/dotnet/aspnetcore/issues/42349 -->
+    <script src="_content/NimbleBlazor/NimbleBlazor.HybridWorkaround.js"></script>
+</body>
+```
+
+## Contributing
+
+Follow the instructions in [CONTRIBUTING.md](/packages/blazor-workspace/NimbleBlazor/CONTRIBUTING.md) to modify this library.