# Commerce Admin Blazor Considerations

## Styling & UI Libraries

> This section seeks to answer the following question:
>
> ***How should commerce-admin implement styling?***

### Potential Candidates

- [MudBlazor](https://mudblazor.com/)
- [Ant Design Blazor](https://antblazor.com/en-US/)
- [MatBlazor](https://www.matblazor.com/)
- [Radzen Blazor](https://razor.radzen.com/get-started)

### Priorities / Requirements

- A UI library must be present in commerce-admin; we do not want to style everything from scratch
- The UI library in use must provide quality documentation with...
- Explorable components with visual examples
- Code examples for each component, preferably with extreme variations for various use cases
- The chosen UI library must include the following components:
- `DataTable` of some kind
- `Typography`
- `Button`
- `NavLink` (or Buttons with NavLink capabilities)
- `Form` component with...
- direct model binding
- data verification
- every input/control under the HTML sun
- The chosen UI library must be customizable with CSS (or some other styling pre-processor)

### Additional Notes

#### MudBlazor

- [Docs](https://mudblazor.com/) are mostly pretty good.
- Components are a bit hard to explore. Users must select components by name from the nav-bar. There's no "Overview" page that shows a basic example of each of them.
- Speed may be a concern? Literally just using their documentation site shows some bugginess & latency. (Note: this may not be an issue with the framework as much as it is just their site.)
- Navigating between a component's visual example with code snippets and its actual API spec is kind of annoying.
- Take the Table component for instance. The examples live [here](https://mudblazor.com/components/table) while the API spec lives [here](https://mudblazor.com/api/table#properties)

#### Ant Design Blazor

- The design of the components is very slick
- Docs are quite intuitive and very in-depth
- Component examples include (1.) wicked variation (2.) code snippets and (3.) an in-depth API spec all in the same place.
- Ant Design is a major UI library that is designed with enterprise scalability in mind. (Note: It touts itself as the second most popular React UI library... probably behind Material)
- The way the components are structured and composed will feel very familiar to any JS web developers.
- Customizability is extensive. I very much doubt we'll find another Blazor framework that matches the customization and scalability of AntD

## CommerceAPI Interop

> This section seeks to answer the following question:
>
> ***How should commerce-admin interact with commerce-api?***

### Potential Candidates

- Use the existing `Fool.Commerce.WebApi.Client`
- Use code generation to generate an API client
- `NSwag`
- Something other than `NSwag`
- ~~Call into services directly~~
- ***Note, though this is technically possible we will not consider this option.***
- Use Refit generated client

### Priorities / Requirements

- Exposed Client methods return typed C# objects
- Exposed Client methods act as a proxy to hit the actual commerce-api endpoint it is associated with
- Exposed Client methods are able to return expected errors and serialize them into specific error types from commerce-api.
- For instance, I should be able to have something that looks like the following. The following function attempts to retrieve a subscription product (by ID) from the client. One possible and expected response from our backend is to respond with `404: Not Found` which indicates a `PromotionNotFoundException` from CommerceApi. I want to be able to do something if that expected behavior occurs:

        public async Task<SubscriptionProductDescription?> GetSubscriptionProduct(int id)
        {
            SubscriptionProductDescription? product = null;
            try
            {
                product = await GenApiClient.GetSubscriptionProductAsync(id);
            }
            catch (ApiException<PromotionNotFoundException> ex)
            {
                Console.WriteLine(
                    $"Expected Exception! Product with ID {id} is not a SubscriptionProduct.\nException: {ex.StatusCode}, {ex.Response}"
                );
            }
            return product;
        }

- Exposed types should follow the same shape, hierarchy, and inheritance as DTOs laid out in `Fool.Commerce`

### Compare & Contrast: Refit vs NSwag

- NSwag
- Pros
- Clean client
- Fully generated
- Cons
- Generation depends on Swagger annotations in controllers. This is error-prone and would require a large overhaul to make sure all of our controller endpoints are well-annotated
- Refit
- Pros
- No repeated use of V1 vs V2 endpoints—all methods will choose one or the other and not expose the other version
- Directly ties into C# objects within `Fool.Commerce` rather than generating them
- Does not depend on controller endpoint annotations
- Cons
- Requires manual writing of client methods

### Additional Notes

#### NSwag API Client Code Generation

##### Additional Reading

- [Blog Post: Generate TypeScript and C# clients with NSwag based on an API](https://blog.logrocket.com/generate-typescript-csharp-clients-nswag-api/)
- [Docs: Get started with NSwag and ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-6.0&tabs=visual-studio)
- [SO: Custom (Nested) Attributes](https://stackoverflow.com/questions/50457080/can-one-make-a-c-sharp-attribute-that-is-a-combination-of-other-attributes-that) this may be a good route to take in order to change how our `ExceptionFilterAttribute` class is used.

## Application Structure

### Priorities / Requirements

- CommerceAdmin must align with Blazor standards regarding folder layout and application structure
- Interaction with CommerceAPI must be abstracted away from Blazor components for sake of testability and encapsulation.