syncfusion-blazor-treegrid

What this skill does

# Implementing Syncfusion Blazor TreeGrid

The Syncfusion Blazor TreeGrid (`SfTreeGrid<TValue>`) renders hierarchical data in a tabular format with expand/collapse rows. It supports self-referential flat data (IdMapping/ParentIdMapping) and nested child collections, combined with a full suite of grid features including editing, filtering, sorting, virtualization, and export.

## When to Use This Skill

- User needs a **hierarchical/tree-structured data table** in a Blazor app
- User mentions **SfTreeGrid**, **TreeGrid**, **IdMapping**, **ParentIdMapping**
- User needs **parent-child rows** with expand/collapse in a grid
- User needs **CRUD operations** on tree-structured data
- User needs to **export**, **filter**, **sort**, or **page** hierarchical data
- User needs to bind TreeGrid to a **GraphQL API** using `GraphQLAdaptor`
- User is working with **organizational charts**, **task hierarchies**, **bill of materials**, **file explorer-style** data in grid form
- User migrating from flat DataGrid to hierarchical TreeGrid
- User setting up TreeGrid in a **Blazor Web App**, **WASM**, **Server**, or **MAUI** project

**Trigger keywords:** TreeGrid, Tree Grid, SfTreeGrid, hierarchical grid, parent-child grid, IdMapping, ParentIdMapping, tree data table, nested grid rows, Syncfusion Blazor tree, GraphQL TreeGrid, GraphQLAdaptor TreeGrid

---

## 🔒 Mandatory Key Rules

These rules govern how this skill MUST behave. They are mandatory and must be strictly followed.

### 1. Purpose and Responsibility

Your responsibility is to interpret any natural‑language user request and provide **accurate**, **complete**, and **validated** information about all supported aspects of the **Syncfusion Blazor TreeGrid**, including:

- Public APIs
- Properties
- Events
- Features
- Behaviors

### 2. Accuracy and API Compliance

The Skill MUST:

- Use **only officially supported** Syncfusion TreeGrid features.
- **NEVER** invent APIs, methods, properties, events, behaviors, or future features.
- **NEVER** provide unsupported or hypothetical code samples.
- ALWAYS follow official Syncfusion component design patterns.

If a feature is **not supported**: clearly state the limitation and suggest a supported alternative when possible.

### 3. Interpreting Natural-Language Requests

When user requests are incomplete:

- Infer reasonable assumptions using official TreeGrid best practices.
- Fill missing gaps with accurate and relevant information.
- Request clarification **only** when essential.

### 4. Handling Unsupported User Requests

If the user asks for an unsupported capability:

- Explicitly state that it is not supported
- Suggest official alternatives or valid workarounds
- NEVER simulate or fabricate impossible functionality

### 5. Design Pattern Enforcement

The Skill MUST follow Syncfusion official patterns, including:

- Correct component structure (`SfTreeGrid`, `TreeGridColumn`, `TreeGridEditSettings`, `TreeGridEvents`, etc.)
- Proper async event and API usage
- Valid configuration properties and enums
- Supported data‑binding approaches (self-referential, hierarchical, remote, custom adaptor, GraphQL)
- Real event patterns and names

### 6. Quality, Completeness & Reliability

The Skill MUST:

- Use only validated and real TreeGrid capabilities
- Provide actionable and implementation‑ready guidance
- Ensure clarity so users can follow without guesswork
- Maintain clean, readable, and professional formatting

### 7. No-Hallucination Safeguard

The Skill MUST NOT:

- Invent non‑existent APIs or behavior
- Suggest unsupported modes, features, or configuration
- Provide incorrect, misleading, or unverifiable code
- Describe undocumented internal behavior

If unsure: ask for clarification **OR** clearly state the limitation.

### 8. Event Name Verification Requirement

**CRITICAL:** Event names MUST be verified against `references/events.md` BEFORE providing code examples. All tree grid events MUST be defined inside the `<TreeGridEvents>` component

**Common Mistakes to Avoid:**

- ❌ `OnSortChange` — Does NOT exist. Use `Sorting`, `Sorted` instead
- ❌ `OnFilterChange` — Does NOT exist. Use `Filtering`, `Filtered` instead


**Rule:** ALWAYS cross-reference `references/events.md` for:

- Exact event names (case-sensitive)
- Event argument types (see **Rule 11** for namespace resolution)
- Whether events are cancelable (✅ or ❌)
- When they fire (before/after operation)

### 9. Read Reference Files Before Writing Code

Before generating **any** code, identify every feature in the request and **read the reference file for each one**. The snippets in this file are abbreviated — they omit critical rules and known pitfalls. Reference files are the authoritative source.

> ⚠️ **Read ALL reference files that apply — not just the one most obvious from the query.**

### 10. Namespace and Type Resolution Rules

**Rule 1:** Always use full namespace qualification to avoid CS0104 "ambiguous reference" errors. Types exist in both `Syncfusion.Blazor.TreeGrid` and `Syncfusion.Blazor.Grids` namespaces.

**Rule 2:** Always include `@using Syncfusion.Blazor.Grids;` in `_Imports.razor` or component to prevent CS0103 "missing reference" errors for:
- Event argument types (`ActionEventArgs`, `RowDataBoundEventArgs`, `BeforeCopyPasteEventArgs`, etc.)
- The `Action` enum (`Action.Sorting`, `Action.Save`, etc.)
- Component classes (`TreeGridPageSettings`, `TreeGridFilterSettings`, `TreeGridSelectionSettings`, etc.)
- Event handler support classes

**Rule 3:** The following event arg types belong to `Syncfusion.Blazor.TreeGrid` — add `@using Syncfusion.Blazor.TreeGrid;` (NOT `Syncfusion.Blazor.Grids`):
- `RowExpandingEventArgs<TValue>`, `RowExpandedEventArgs<TValue>`
- `RowCollapsingEventArgs<TValue>`, `RowCollapsedEventArgs<TValue>`
- `CheckBoxChangeEventArgs<TValue>`

**Type Reference:**

| Type | Namespace | Example |
|---|---|---|
| **FilterType** | TreeGrid | `Syncfusion.Blazor.TreeGrid.FilterType.Excel` |
| **EditMode** | TreeGrid | `Syncfusion.Blazor.TreeGrid.EditMode.Row` |
| **CopyHierarchyType** | TreeGrid | `Syncfusion.Blazor.TreeGrid.CopyHierarchyType.Both` |
| **Action** | Grids | `Syncfusion.Blazor.Grids.Action.Save` |
| **TextAlign** | Grids | `Syncfusion.Blazor.Grids.TextAlign.Right` |
| **ColumnType** | Grids | `Syncfusion.Blazor.Grids.ColumnType.Date` |
| **EditType** | Grids | `Syncfusion.Blazor.Grids.EditType.DatePickerEdit` |
| **SelectionMode** | Grids | `Syncfusion.Blazor.Grids.SelectionMode.Row` |
| **SelectionType** | Grids | `Syncfusion.Blazor.Grids.SelectionType.Multiple` |
| **ClipMode** | Grids | `Syncfusion.Blazor.Grids.ClipMode.Ellipsis` |
| **GridLine** | Grids | `Syncfusion.Blazor.Grids.GridLine.Horizontal` |
| **AggregateType** | Grids | `Syncfusion.Blazor.Grids.AggregateType.Sum` |
| **CellSelectionMode** | Grids | `Syncfusion.Blazor.Grids.CellSelectionMode.Box` |
---

## Component Overview

```razor
<SfTreeGrid DataSource="@TreeData"
            IdMapping="TaskId"
            ParentIdMapping="ParentId"
            TreeColumnIndex="1"
            AllowSorting="true"
            AllowFiltering="true"
            AllowPaging="true">
    <TreeGridColumns>
        <TreeGridColumn Field="TaskId" HeaderText="ID" Width="80" IsPrimaryKey="true" />
        <TreeGridColumn Field="TaskName" HeaderText="Task Name" Width="200" />
        <TreeGridColumn Field="Duration" HeaderText="Duration" Width="100" />
        <TreeGridColumn Field="Progress" HeaderText="Progress" Width="100" />
    </TreeGridColumns>
</SfTreeGrid>
```

**Key concepts:**
- `IdMapping` — property name that uniquely identifies each row
- `ParentIdMapping` — property name pointing to the parent row's ID (null/0 = root)
- `TreeColumnIndex` — column index that shows the expand/collapse icon (0-based)

---

## Navigation Guide

### Setup & Getting Started
- **Read:** [references/getting-started.md](references/getting-started.md)
  - NuGet install, `_Imports.razor`, `Program.cs`, theme/script setup, basic gri