# 07 — Dataset Explorer

## 1. High-Level Overview

**Purpose**: Browse, filter, edit, split, and export the dataset. Reuses `CanvasEditor` from `06_annotations` for in-place bbox editing on dataset thumbnails.

**Architectural Pattern**: Single-page feature with one route component composing local panels.

**Upstream dependencies**: `00_foundation`, `01_api-transport`, `03_shared-ui` (FlightContext, ConfirmDialog, DetectionClasses), `06_annotations` (`CanvasEditor` — cross-feature edge).

**Downstream consumers**: `10_app-shell` (routed at `/dataset`).

## 2. Internal Interfaces

| Export | Notes |
|--------|-------|
| `DatasetPage()` | Top-level route component. Loads paged dataset items, applies filters (class, affiliation, status, flight), renders thumbnail grid + edit pane. |

## 3. External API Specification

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/annotations/dataset` | Paged list with filters |
| GET | `/api/annotations/dataset/{id}` | Detail |
| PUT | `/api/annotations/dataset/{id}` | Update (class, status, bbox) |
| DELETE | `/api/annotations/dataset/{id}` | Delete |
| POST | `/api/annotations/dataset/bulk-status` | Bulk status update (numeric per finding cross-check) |
| POST | `/api/annotations/dataset/{id}/split` | Split tile |

## 5. Implementation Details

**State Management**: Page-local. Uses `useDebounce` for filter inputs and `useResizablePanel` for the editor pane.

**Findings** (13 numbered, from `src__features__dataset__DatasetPage.md`):

1. **No keyboard shortcuts** at all.
2. **No "Refresh thumbnails"** action.
3. **No virtualisation** — long lists render all thumbnails.
4. **Editor tab does not save** — confirmed regression.
5. **Magic `mediaType=1`** literal — should be the typed enum.
6. **Dead `ConfirmDialog` import** — never used.
7. **Silent `try/catch`** in delete handler.
8. **Status filter conflates `None` with `All`** — depends on the `AnnotationStatus` enum drift fix (`00_foundation/types/index.ts`).
9. **`classNum=0` sentinel collides with real class 0** — needs explicit "all classes" sentinel.
10. **`mediaType=1` again** — appears twice.
11. **Bulk-status request** uses string status names; spec wants numerics — already retagged for parent-doc fix (state.json 02:18Z note covered the spec side).
12. **DatasetItem.isSplit** missing in the parent-doc response schema — cross-repo PARENT-DOC FIX applied.
13. **Cross-feature `CanvasEditor` import** — finding #14 (cross-link to enum drift + isSplit gap).

**Key Dependencies**: `react-dropzone` (export trigger), `@hello-pangea/dnd` (potentially, for reordering — verify in Step 3).

## 6b. WPF gap analysis (vs `suite/annotations-research`)

> Cross-check of the legacy `Azaion.Dataset.DatasetExplorer` window (`Azaion.Dataset/DatasetExplorer.xaml`) against the current React `DatasetPage`. **Step 4 correction**: an earlier draft of this table claimed several WPF features were missing that are in fact already implemented. Re-read of `src/features/dataset/DatasetPage.tsx` corrected the table below.

| WPF feature | Anchor in `annotations-research` | React status | Owner |
|------------|----------------------------------|--------------|-------|
| **Class Distribution chart tab** (3rd tab — horizontal bars per `DetectionClass`, bar tinted with the class color) | `Azaion.Dataset/Controls/ClassDistribution.xaml` + `DatasetExplorer.xaml:146-148` | **Implemented** — `DatasetPage.tsx:151` has three tabs (`annotations`, `editor`, `distribution`); `loadDistribution()` calls `GET /api/annotations/dataset/class-distribution`. Step-4 verify the bar tint matches `classColors`. | — |
| **"Show only annotations with objects" checkbox** in left filter pane | `DatasetExplorer.xaml:89-95` `ShowWithObjectsOnlyChBox` | **Implemented** — `DatasetPage.tsx:110-114`, state name `objectsOnly`. | — |
| **Validate button (bulk-validate selected annotations to `AnnotationStatus.Validated`)** | `DatasetExplorer.xaml:177-200` `ValidateBtn` + `ValidateAnnotationsClick` | **Implemented** — `DatasetPage.tsx:142-146` Validate button appears when `selectedIds.size > 0`; `handleValidate()` posts to `/api/annotations/dataset/bulk-status`. **Gap is the `[V]` keyboard shortcut**, not the button. | `DatasetPage` (shortcut only) |
| **Refresh thumbnails button + progress bar** | `DatasetExplorer.xaml:205-247` `RefreshThumbnailsButtonItem` + `RefreshProgressBarItem` | Button missing (finding #2); progress UI also missing | `DatasetPage` + an as-yet-undefined refresh service endpoint |
| **`SelectedAnnotationName` status indicator** (bottom-right of status bar) | `DatasetExplorer.xaml:252-254` | Missing | `DatasetPage` |
| **Generic `StatusText` slot** | `DatasetExplorer.xaml:249-251` | Missing | `DatasetPage` |
| **Seed annotation highlight** (`IsSeed=true` thumbnails get an 8 px IndianRed border) | `DatasetExplorer.xaml:15-29` thumbnail template | Missing — `DatasetItem.isSeed` shape unverified against suite spec (cross-link to `00_foundation/types/index.ts`). | `DatasetPage` + types |
| **Thumbnail caption** (image name + `CreatedDate: CreatedEmail`) | `DatasetExplorer.xaml:42-56` | Likely missing or simplified — verify in Step 4 against current React render. | `DatasetPage` |
| **Keyboard shortcuts `[1]–[9]`, `[Enter]`, `[Del]`, `[X]`, `[V]`, arrows, PgUp/PgDn, `[Esc]`** for inline editor | `DatasetExplorer.xaml.cs` (listed in `_docs/legacy/wpf-era.md §5`) | Missing entirely (finding #1) | `DatasetPage` |
| **Editor tab actually saves** | WPF wires `ExplorerEditor` → `AnnotationService.OnAnnotationCreated` etc. | **Broken in React** (finding #4 — Editor tab does not save). PRIORITY Step 4. | `DatasetPage` + `06_annotations/CanvasEditor` |
| **`DetectionClasses` strip in left pane** (same control reused from Annotator) | `DatasetExplorer.xaml:85-88` | Present (via `03_shared-ui/DetectionClasses`) | — |
| **Filter `TextBox`** | `DatasetExplorer.xaml:112-115` `TbSearch` with `TextChanged` debounce | Present (uses `00_foundation/useDebounce`) | — |
| **Virtualised thumbnail grid** (`vwp:GridView` from `WpfToolkit.VirtualizingWrapPanel`) | `DatasetExplorer.xaml:126-135` | **Missing virtualisation** (finding #3) — long lists render all thumbnails. | `DatasetPage` |

### Decisions required at Step 4.5 (Architecture Vision)

- **Refresh-thumbnails action** — is the existing thumbnail refresh strategy (server-side on annotation save) acceptable, or do we need a manual "Refresh" affordance like the WPF era?
- **Status-bar surfaces** (`StatusText`, `SelectedAnnotationName`) — port the WPF status bar verbatim, or rely on existing toasts and selection counters?
- **Seed annotation concept** (`IsSeed=true` highlight) — does the modern API still expose `IsSeed`, and is the visual still desired?
- **Inline editor save** — is the broken save (#4) a regression to fix or a feature to be redesigned?

## 7. Caveats & Edge Cases

- **Cross-feature import** of `CanvasEditor` (`06_annotations`). Either lift to a shared `components/canvas/` or accept the edge — record in module-layout / baseline scan.
- **Editor tab broken** (#4) — PRIORITY Step 4.
- **Filter sentinels colliding** (#8, #9) — wire-format consistency depends on enum drift fix.
- **WPF gap analysis above** lists ~12 missing affordances. Highest user-impact: virtualisation, Refresh thumbnails, keyboard shortcuts, broken editor save. Highest design-impact: Class Distribution chart (entirely missing third tab).

## 8. Dependency Graph

**Must be implemented after**: `00_foundation`, `01_api-transport`, `03_shared-ui`, `06_annotations` (`CanvasEditor`).

**Can be implemented in parallel with**: `04_login`, `05_flights`, `08_admin`, `09_settings`.

**Blocks**: `10_app-shell` only.

## Module Inventory

| Path | Module Doc |
|------|------------|
| `src/features/dataset/DatasetPage.tsx` | `_docs/02_document/modules/src__features__dataset__DatasetPage.md` |