@ngxtm/devkit 3.4.0 → 3.5.0

package/rules/dotnet/blazor/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: Blazor
+description: Blazor component patterns for interactive web UIs.
+metadata:
+  labels: [blazor, components, wasm, server]
+  triggers:
+    files: ['**/*.razor', '**/*.razor.cs']
+    keywords: [Component, Parameter, CascadingParameter, EventCallback, StateHasChanged]
+---
+
+# Blazor
+
+## **Priority: P1 (OPERATIONAL)**
+
+Blazor component patterns for interactive web UIs.
+
+## Implementation Guidelines
+
+- **Components**: Keep components focused. Split large components into smaller ones.
+- **Parameters**: Use `[Parameter]` for one-way, `EventCallback` for two-way binding.
+- **Cascading Values**: Use for app-wide state (theme, user context).
+- **State Management**: Component state for local, Fluxor/custom service for global.
+- **Forms**: `EditForm` with `DataAnnotationsValidator` or FluentValidation.
+- **JS Interop**: Use `IJSRuntime` sparingly. Prefer Blazor bindings.
+- **Render Modes**: Choose based on requirements (Server, WASM, Auto in .NET 8+).
+- **Streaming**: Use `[StreamRendering]` for long-loading components.
+
+## Anti-Patterns
+
+- **No direct DOM manipulation**: Use Blazor bindings and refs.
+- **No `StateHasChanged()` in lifecycle**: Called automatically after lifecycle methods.
+- **No heavy computation in render**: Move to `OnInitialized` or background task.
+- **No sync JS interop in Server mode**: Causes UI blocking.
+
+## Code
+
+```razor
+@* UserList.razor *@
+@page "/users"
+@attribute [StreamRendering]
+@inject IUserService UserService
+
+<PageTitle>Users</PageTitle>
+
+<h3>Users</h3>
+
+@if (_users is null)
+{
+    <p><em>Loading...</em></p>
+}
+else if (_users.Count == 0)
+{
+    <p>No users found.</p>
+}
+else
+{
+    <div class="user-grid">
+        @foreach (var user in _users)
+        {
+            <UserCard User="user" OnDelete="HandleDelete" />
+        }
+    </div>
+}
+
+@code {
+    private List<User>? _users;
+
+    protected override async Task OnInitializedAsync()
+    {
+        _users = await UserService.GetAllAsync();
+    }
+
+    private async Task HandleDelete(int userId)
+    {
+        await UserService.DeleteAsync(userId);
+        _users = await UserService.GetAllAsync();
+    }
+}
+```
+
+```razor
+@* UserCard.razor - Reusable component *@
+<div class="card">
+    <h5>@User.Name</h5>
+    <p>@User.Email</p>
+    <button @onclick="() => OnDelete.InvokeAsync(User.Id)">Delete</button>
+</div>
+
+@code {
+    [Parameter, EditorRequired]
+    public User User { get; set; } = default!;
+
+    [Parameter]
+    public EventCallback<int> OnDelete { get; set; }
+}
+```
+
+```razor
+@* EditForm with validation *@
+<EditForm Model="@_model" OnValidSubmit="HandleSubmit" FormName="CreateUser">
+    <DataAnnotationsValidator />
+    <ValidationSummary class="text-danger" />
+
+    <div class="mb-3">
+        <label class="form-label">Name</label>
+        <InputText @bind-Value="_model.Name" class="form-control" />
+        <ValidationMessage For="@(() => _model.Name)" />
+    </div>
+
+    <div class="mb-3">
+        <label class="form-label">Email</label>
+        <InputText @bind-Value="_model.Email" class="form-control" type="email" />
+        <ValidationMessage For="@(() => _model.Email)" />
+    </div>
+
+    <button type="submit" class="btn btn-primary" disabled="@_isSubmitting">
+        @if (_isSubmitting)
+        {
+            <span class="spinner-border spinner-border-sm"></span>
+        }
+        Submit
+    </button>
+</EditForm>
+
+@code {
+    private CreateUserModel _model = new();
+    private bool _isSubmitting;
+
+    private async Task HandleSubmit()
+    {
+        _isSubmitting = true;
+        await UserService.CreateAsync(_model);
+        _isSubmitting = false;
+        NavigationManager.NavigateTo("/users");
+    }
+}
+```
+
+## Reference & Examples
+
+For lifecycle, state management, and JS interop:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+aspnet-core | razor-pages | security

package/rules/dotnet/blazor/references/REFERENCE.md

@@ -0,0 +1,392 @@
+# Blazor Reference
+
+Component lifecycle, state management, and advanced patterns.
+
+## References
+
+- [**Lifecycle**](lifecycle.md) - Component lifecycle methods.
+- [**State Management**](state-management.md) - Fluxor, cascading values.
+- [**JS Interop**](js-interop.md) - JavaScript interoperability.
+
+## Component Lifecycle
+
+```csharp
+@code {
+    // 1. Called when component is first initialized (before rendering)
+    protected override void OnInitialized()
+    {
+        // Sync initialization
+    }
+
+    // 1b. Async version (preferred for data loading)
+    protected override async Task OnInitializedAsync()
+    {
+        // Load initial data
+        _data = await DataService.GetAsync();
+    }
+
+    // 2. Called when parameters are set/changed
+    protected override void OnParametersSet()
+    {
+        // React to parameter changes
+    }
+
+    protected override async Task OnParametersSetAsync()
+    {
+        // Async parameter processing
+    }
+
+    // 3. Called after component has rendered
+    protected override void OnAfterRender(bool firstRender)
+    {
+        if (firstRender)
+        {
+            // First render only - initialize JS libraries
+        }
+        // Every render - update DOM-dependent state
+    }
+
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (firstRender)
+        {
+            await JSRuntime.InvokeVoidAsync("initializeChart", _chartElement);
+        }
+    }
+
+    // 4. Optimize re-rendering
+    protected override bool ShouldRender()
+    {
+        // Return false to prevent re-rendering
+        return _hasChanged;
+    }
+
+    // 5. Cleanup when component is disposed
+    public void Dispose()
+    {
+        // Unsubscribe from events, dispose resources
+        _subscription?.Dispose();
+    }
+
+    // Async dispose (IAsyncDisposable)
+    public async ValueTask DisposeAsync()
+    {
+        await JSRuntime.InvokeVoidAsync("cleanup");
+    }
+}
+```
+
+## State Management Patterns
+
+```csharp
+// 1. Cascading Values - App-wide state
+// App.razor or Routes.razor
+<CascadingValue Value="@_themeState">
+    <CascadingValue Value="@_userState">
+        <Router AppAssembly="@typeof(App).Assembly">
+            ...
+        </Router>
+    </CascadingValue>
+</CascadingValue>
+
+@code {
+    private ThemeState _themeState = new();
+    private UserState _userState = new();
+}
+
+// Consuming component
+@code {
+    [CascadingParameter]
+    public ThemeState Theme { get; set; } = default!;
+
+    [CascadingParameter]
+    public UserState User { get; set; } = default!;
+}
+```
+
+```csharp
+// 2. State Container Service
+public class CartState
+{
+    private readonly List<CartItem> _items = [];
+
+    public IReadOnlyList<CartItem> Items => _items.AsReadOnly();
+    public decimal Total => _items.Sum(i => i.Price * i.Quantity);
+
+    public event Action? OnChange;
+
+    public void AddItem(CartItem item)
+    {
+        _items.Add(item);
+        NotifyStateChanged();
+    }
+
+    public void RemoveItem(int productId)
+    {
+        _items.RemoveAll(i => i.ProductId == productId);
+        NotifyStateChanged();
+    }
+
+    private void NotifyStateChanged() => OnChange?.Invoke();
+}
+
+// Registration
+builder.Services.AddScoped<CartState>();
+
+// Component usage
+@inject CartState Cart
+@implements IDisposable
+
+<div>Total: @Cart.Total.ToString("C")</div>
+
+@code {
+    protected override void OnInitialized()
+    {
+        Cart.OnChange += StateHasChanged;
+    }
+
+    public void Dispose()
+    {
+        Cart.OnChange -= StateHasChanged;
+    }
+}
+```
+
+```csharp
+// 3. Fluxor (Redux pattern)
+// State
+public record CounterState(int Count);
+
+public class CounterFeature : Feature<CounterState>
+{
+    public override string GetName() => "Counter";
+    protected override CounterState GetInitialState() => new(0);
+}
+
+// Actions
+public record IncrementAction();
+public record DecrementAction();
+public record SetCountAction(int Count);
+
+// Reducers
+public static class CounterReducers
+{
+    [ReducerMethod]
+    public static CounterState OnIncrement(CounterState state, IncrementAction _)
+        => state with { Count = state.Count + 1 };
+
+    [ReducerMethod]
+    public static CounterState OnDecrement(CounterState state, DecrementAction _)
+        => state with { Count = state.Count - 1 };
+
+    [ReducerMethod]
+    public static CounterState OnSetCount(CounterState state, SetCountAction action)
+        => state with { Count = action.Count };
+}
+
+// Component
+@inject IState<CounterState> CounterState
+@inject IDispatcher Dispatcher
+
+<p>Count: @CounterState.Value.Count</p>
+<button @onclick="Increment">+</button>
+<button @onclick="Decrement">-</button>
+
+@code {
+    private void Increment() => Dispatcher.Dispatch(new IncrementAction());
+    private void Decrement() => Dispatcher.Dispatch(new DecrementAction());
+}
+```
+
+## JS Interop
+
+```csharp
+// Calling JavaScript from C#
+@inject IJSRuntime JS
+
+@code {
+    private ElementReference _inputElement;
+
+    // Call JS function
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (firstRender)
+        {
+            await JS.InvokeVoidAsync("initializeComponent", _inputElement);
+        }
+    }
+
+    // Call JS function with return value
+    private async Task<string> GetLocalStorage(string key)
+    {
+        return await JS.InvokeAsync<string>("localStorage.getItem", key);
+    }
+
+    // Focus element
+    private async Task FocusInput()
+    {
+        await _inputElement.FocusAsync();
+    }
+}
+```
+
+```javascript
+// wwwroot/js/interop.js
+window.initializeComponent = (element) => {
+    // Initialize third-party library
+    new SomeLibrary(element);
+};
+
+window.blazorInterop = {
+    showAlert: (message) => alert(message),
+    getWindowSize: () => ({ width: window.innerWidth, height: window.innerHeight })
+};
+```
+
+```csharp
+// Calling C# from JavaScript
+// In component
+@inject IJSRuntime JS
+
+@code {
+    private DotNetObjectReference<MyComponent>? _objRef;
+
+    protected override void OnInitialized()
+    {
+        _objRef = DotNetObjectReference.Create(this);
+    }
+
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (firstRender)
+        {
+            await JS.InvokeVoidAsync("registerCallback", _objRef);
+        }
+    }
+
+    [JSInvokable]
+    public void HandleCallback(string data)
+    {
+        // Called from JavaScript
+        Console.WriteLine($"Received: {data}");
+        StateHasChanged();
+    }
+
+    public void Dispose()
+    {
+        _objRef?.Dispose();
+    }
+}
+```
+
+```javascript
+// JavaScript calling C#
+window.registerCallback = (dotNetRef) => {
+    window.myCallback = (data) => {
+        dotNetRef.invokeMethodAsync('HandleCallback', data);
+    };
+};
+
+// Later...
+myCallback('Some data from JS');
+```
+
+## Render Modes (.NET 8+)
+
+```razor
+@* Static Server Rendering (SSR) - Default *@
+@rendermode InteractiveServer
+@rendermode InteractiveWebAssembly
+@rendermode InteractiveAuto
+
+@* Per-component render mode *@
+<Counter @rendermode="InteractiveServer" />
+<Counter @rendermode="InteractiveWebAssembly" />
+
+@* Streaming rendering for slow data *@
+@attribute [StreamRendering]
+
+<h1>Dashboard</h1>
+
+@if (_data is null)
+{
+    <p>Loading dashboard data...</p>
+}
+else
+{
+    <DashboardContent Data="_data" />
+}
+
+@code {
+    private DashboardData? _data;
+
+    protected override async Task OnInitializedAsync()
+    {
+        // This data streams to the client as it loads
+        _data = await SlowDataService.GetDashboardAsync();
+    }
+}
+```
+
+## Error Handling
+
+```razor
+@* ErrorBoundary for graceful error handling *@
+<ErrorBoundary @ref="_errorBoundary">
+    <ChildContent>
+        <RiskyComponent />
+    </ChildContent>
+    <ErrorContent Context="exception">
+        <div class="alert alert-danger">
+            <h4>Something went wrong</h4>
+            <p>@exception.Message</p>
+            <button @onclick="Recover">Try Again</button>
+        </div>
+    </ErrorContent>
+</ErrorBoundary>
+
+@code {
+    private ErrorBoundary? _errorBoundary;
+
+    private void Recover()
+    {
+        _errorBoundary?.Recover();
+    }
+}
+```
+
+## Authentication in Blazor
+
+```razor
+@* Show content based on auth state *@
+<AuthorizeView>
+    <Authorized>
+        <p>Hello, @context.User.Identity?.Name!</p>
+        <a href="account/logout">Logout</a>
+    </Authorized>
+    <NotAuthorized>
+        <a href="account/login">Login</a>
+    </NotAuthorized>
+</AuthorizeView>
+
+@* Role-based content *@
+<AuthorizeView Roles="Admin,Manager">
+    <Authorized>
+        <AdminPanel />
+    </Authorized>
+    <NotAuthorized>
+        <p>Access denied</p>
+    </NotAuthorized>
+</AuthorizeView>
+
+@* Policy-based content *@
+<AuthorizeView Policy="CanEditOrders">
+    <button @onclick="EditOrder">Edit</button>
+</AuthorizeView>
+
+@* Protect entire page *@
+@page "/admin"
+@attribute [Authorize(Roles = "Admin")]
+
+<h1>Admin Dashboard</h1>
+```

package/rules/dotnet/language/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: C# Language Patterns
+description: Modern C# standards for type safety, performance, and maintainability.
+metadata:
+  labels: [csharp, dotnet, language, types, async]
+  triggers:
+    files: ['**/*.cs', '**/*.csproj']
+    keywords: [class, record, interface, async, await, linq, nullable, span]
+---
+
+# C# Language Patterns
+
+## **Priority: P0 (CRITICAL)**
+
+Modern C# standards for type-safe, performant, maintainable code.
+
+## Implementation Guidelines
+
+- **Nullable Reference Types**: Enable `<Nullable>enable</Nullable>`. Use `?` for nullable, avoid `!` except when compiler can't infer.
+- **Records**: `record` for immutable DTOs, `record struct` for stack-allocated value types.
+- **Pattern Matching**: `is` patterns, `switch` expressions, property/positional patterns.
+- **Async/Await**: Always use `CancellationToken`. `ValueTask` for hot paths. `ConfigureAwait(false)` in libraries.
+- **LINQ**: Prefer method syntax. Avoid multiple enumerations (`ToList()` once). Use `AsNoTracking()` for read-only EF queries.
+- **Generics**: Constraints (`where T : class, new()`), covariance (`out T`), contravariance (`in T`).
+- **Spans**: `Span<T>`, `ReadOnlySpan<T>` for zero-allocation slicing.
+- **Primary Constructors**: C# 12+ `class Foo(int x)` for concise DI.
+- **Collection Expressions**: C# 12+ `[1, 2, 3]` syntax.
+- **Raw String Literals**: `"""multi-line"""` for SQL, JSON templates.
+
+## Anti-Patterns
+
+- **No `async void`**: Use `async Task`. Exception: event handlers.
+- **No `Task.Result`/`.Wait()`**: Deadlock risk. Always `await`.
+- **No `DateTime.Now`**: Use `DateTimeOffset.UtcNow` for timezone safety.
+- **No string concat in loops**: Use `StringBuilder` or `string.Join`.
+- **No `!` abuse**: Prefer null checks or `??` over null-forgiving.
+
+## Code
+
+```csharp
+// Record with primary constructor
+public record UserDto(string Name, string Email);
+
+// Pattern matching with switch expression
+string GetStatus(Order order) => order switch
+{
+    { Status: OrderStatus.Pending } => "Waiting",
+    { Status: OrderStatus.Shipped, TrackingNumber: not null } => "In Transit",
+    { IsCancelled: true } => "Cancelled",
+    _ => "Unknown"
+};
+
+// Async with cancellation token
+async Task<User?> GetUserAsync(int id, CancellationToken ct = default)
+{
+    return await _db.Users
+        .AsNoTracking()
+        .FirstOrDefaultAsync(u => u.Id == id, ct);
+}
+
+// Span for zero-allocation parsing
+ReadOnlySpan<char> GetFirstWord(ReadOnlySpan<char> text)
+{
+    int idx = text.IndexOf(' ');
+    return idx < 0 ? text : text[..idx];
+}
+
+// Primary constructor (C# 12)
+public class UserService(IUserRepository repo, ILogger<UserService> logger)
+{
+    public async Task<User?> GetAsync(int id) => await repo.GetByIdAsync(id);
+}
+```
+
+## Reference & Examples
+
+For advanced patterns, spans, and nullable annotations:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+best-practices | security | tooling