# Conventions

For core framework conventions (Ac prefix, Session/Transaction pattern, etc.) see `AyCode.Core/docs/CONVENTIONS.md`.

## Framework-First Placement

Follow the doctrine in `../AyCode.Core/docs/CONVENTIONS.md#framework-first-placement`. Same verdicts and hard rules apply.

**Blazor/MAUI-specific additions:**
- UI types follow the generic-base pattern — consumer types are type parameters, not hardcoded concrete types
- DevExpress-wrapper components stay generic across consumers
- MAUI platform code = platform abstractions only, not consumer-app specifics

## Naming

- **Grid components:** `Grid{Entity}Base` (e.g., `GridPartnerBase`, `GridShippingBase`). Suffix `Base` because consuming projects may extend them.
- **CardView components:** Inside `Components/CardViews/` — card-style wrappers around DxGrid for mobile-friendly layouts.
- **Services:** `Ac{Domain}ServiceBase` for abstract bases. Platform-specific implementations in consuming projects.
- **ViewModels:** In `AyCode.Blazor.Models/ViewModels/` — suffixed with `ViewModel` or kept as plain model classes.

## XML Documentation

`<summary>` — brief, developer-facing, readable in VS IntelliSense tooltip. NO implementation details, NO wire-format / byte-level / perf specifics — those live in `docs/TOPIC/*.md`. Add `<example>` only when usage is non-obvious; otherwise omit.

## Component Patterns

- **DevExpress 25.1.3 exclusively** — never mix with other Blazor component libraries.
- **DxGrid + AcSignalRDataSource** — grids always bind to SignalR-backed data sources, not REST.
- **AcExpressionNode** for grid filters — LINQ expressions are serialized client-side and evaluated server-side.
- **Layout persistence** — grid column order/width saved to localStorage via `MgGridBase`.
- **ExpressionHelper** services handle AcLinq ↔ DevExpress filter conversion.

## MAUI Patterns

- **Platform folders** (`Platforms/Android/`, `iOS/`, `Windows/`) for platform-specific code.
- **BlazorWebView** hosts the same Blazor components used in Server mode.
- **IFormFactor** interface — each platform provides its own implementation (Phone, Tablet, Desktop, Web, WebAssembly).

## Blazor Patterns

- **Razor component + code-behind** — `.razor` for markup, `.razor.cs` for logic.
- **Cascading parameters** for authentication state and layout context.
- **JS interop** via scoped modules (`ExampleJsInterop.cs` pattern).

## DLL References

- All AyCode.Core project references are via **DLL** (not ProjectReference) — this is intentional to separate build graphs.
- DevExpress references are NuGet packages pinned to **25.1.3**.