AyCode.Blazor/AyCode.Blazor.Components/docs/MGGRID/README.md

MgGrid System

Comprehensive documentation for the MgGrid component family — the primary UI data grid pattern in the AyCode.Blazor framework. Source: Components/Grids/ For SignalR transport: AyCode.Services/docs/SIGNALR/README.md (in AyCode.Core repo) For AcSignalRDataSource: AyCode.Services.Server/docs/SIGNALR/SIGNALR_DATASOURCE.md (in AyCode.Core repo)

Overview

MgGridBase is an abstract generic Blazor component that extends DevExpress DxGrid with:

• Automatic SignalR CRUD via AcSignalRDataSource (see AyCode.Core docs)
• Layout persistence — column order, widths, sorting, grouping auto-saved to localStorage
• Master-detail hierarchy — nested grids share context via CascadingParameter
• InfoPanel integration — side panel shows focused row details, supports edit mode
• Fullscreen mode — standalone overlay or via MgGridWithInfoPanel wrapper
• Change tracking — client-side tracking with server sync via SaveChangesAsync

Detailed Documentation

File	Topics
MGGRID_PARAMETERS.md	Component parameters (required, CRUD tags, data & context, display), event callbacks, default grid settings
MGGRID_CRUD.md	Lifecycle, CRUD operations, ID generation, edit flow, disposal
MGGRID_LAYOUT.md	Layout persistence (storage keys, three tiers, operations, persisted state)
MGGRID_DETAIL.md	Master-detail hierarchy
MGGRID_RENDERING.md	Fullscreen mode, rendering
MGGRID_INFOPANEL.md	MgGridInfoPanel, MgGridWithInfoPanel wrapper, responsive layout, templates, editors
MGGRID_TOOLBAR.md	MgGridToolbarTemplate (buttons, parameters, state)
MGGRID_COLUMNS.md	MgGridDataColumn (InfoPanel params, UrlLink)
MGGRID_DATASOURCE.md	MgGridSignalRDataSource (server-side data, local cache, background refresh)
MGGRID_ISSUES.md	Known issues (GRID-I-*, GRID-B-*) — currently none formally tracked
MGGRID_TODO.md	Planned work (GRID-T-*) — refactors, missing features, optimizations

Component Hierarchy

DxGrid (DevExpress)
  └── MgGridBase<TSignalRDataSource, TDataItem, TId, TLoggerClient>   (AyCode.Blazor — abstract)
        └── [Project-specific adapter]            ← consumer fixes TSignalRDataSource, TId, TLoggerClient
              └── [Concrete entity grid]          ← consumer sets CRUD tags in constructor

Companion Components

Component	Purpose	Docs
MgGridWithInfoPanel	DxSplitter wrapper: grid + InfoPanel, fullscreen, splitter persistence	MGGRID_INFOPANEL.md
MgGridToolbarBase	DxToolbar base with Grid reference, RefreshClick callback	MGGRID_TOOLBAR.md
MgGridToolbarTemplate	Full toolbar: CRUD, navigation, layout menu, fullscreen, export	MGGRID_TOOLBAR.md
MgGridDataColumn	Extended DxGridDataColumn with InfoPanel params and UrlLink	MGGRID_COLUMNS.md
MgGridInfoPanel	Default InfoPanel: column-value pairs, edit mode, typed editors	MGGRID_INFOPANEL.md
MgGridSignalRDataSource	GridCustomDataSource wrapper: server-side filter/sort/page, local cache	MGGRID_DATASOURCE.md

Generic Type Parameters

MgGridBase<TSignalRDataSource, TDataItem, TId, TLoggerClient>

Parameter	Constraint	Purpose
TSignalRDataSource	: AcSignalRDataSource<…>	SignalR-backed data source (see AyCode.Services.Server/docs/SIGNALR/SIGNALR_DATASOURCE.md in AyCode.Core repo)
TDataItem	: class, IId<TId>	Entity type displayed in the grid
TId	: struct	Primary key type (int, Guid)
TLoggerClient	: AcLoggerBase	Logger for diagnostics

Usage Example (Project-Specific Adapter)

// Project adapter — fixes TSignalRDataSource, TId, TLoggerClient for the entire project
public class MyProjectGridBase<TDataItem>
    : MgGridBase<MySignalRDataSource<TDataItem>, TDataItem, int, MyLoggerClient>
    where TDataItem : class, IId<int>
{
    [Inject] public required MyLoggedInModel LoggedInModel { get; set; }
    protected override int GetLayoutUserId() => LoggedInModel.UserId;
}

// Concrete grid — only TDataItem remains open
public class GridOrderBase : MyProjectGridBase<Order>
{
    public GridOrderBase()
    {
        GetAllMessageTag = MySignalRTags.GetOrders;
        AddMessageTag    = MySignalRTags.AddOrder;
        UpdateMessageTag = MySignalRTags.UpdateOrder;
    }
}

Interface: IMgGridBase

The public contract exposed to companion components (toolbar, InfoPanel, wrapper):

Member	Type	Description
IsSyncing	bool	Whether SignalR sync is in progress
Caption	string	Grid title
GridEditState	MgGridEditState	None / New / Edit
ParentGrid	IMgGridBase?	Parent in master-detail hierarchy
GetRootGrid()	IMgGridBase	Walks to topmost grid
StepPrevRow()	void	Navigate to previous visible row
StepNextRow()	void	Navigate to next visible row
InfoPanelInstance	IInfoPanelBase?	Resolved InfoPanel reference
IsFullscreen	bool	Current fullscreen state
AutomaticLayoutStorageKey	string	Current auto-save storage key
ToggleFullscreen()	void	Toggle fullscreen mode
SaveUserLayoutAsync()	Task	Save layout manually
LoadUserLayoutAsync()	Task	Load manually saved layout
ResetLayoutAsync()	Task	Reset to default layout
HasUserLayoutAsync()	Task<bool>	Check if manual save exists

Event Args Classes

Class	Base	Extra Properties
GridDataItemChangedEventArgs<T>	—	Grid, DataItem, TrackingState, CancelStateChangeInvoke
GridDataItemChangingEventArgs<T>	GridDataItemChangedEventArgs<T>	IsCanceled