# Example: screen document

Doc gen produces one screen document per non-utility screen in a web front end,
written to `docs/screens/<slug>.md` from the `.aspx` markup and its code-behind.

## What reviewers should check

- Sources cite the real `.aspx` and its code-behind, never an analysis file or
  a generated findings document.
- Every row in `## Operations` records a `Delegates to` value that is either a
  resolvable link, a `†`-marked dotted library name, or `—` for screen-local
  handlers; a bare class or method name is a contract violation.
- Business rule IDs in the table are links to their anchor on
  `docs/application/business-rules.md` — bare `BR-SCR-001` text is a blocker.
- A `## Screen flow diagram` appears only when the screen has three or more
  outbound navigations, and it uses a standard ```` ```mermaid ```` fence.
- `## Infragistics components` is present only when the screen actually hosts
  Infragistics controls, and every listed control ID exists in the markup.
- Navigation targets resolve to sibling screen documents that this run
  generated.

## Example

The document below is a complete, correct `claim-search.md` for a fictional
application.

[View rendered example](rendered/screens/claim-search.md) — the same document as a real page, so you can compare rendering as well as source.

````markdown
---
title: Claim Search
summary: Lets claims staff locate existing claims by claim number, claimant, or employer before opening or filing a claim.
status: draft
owner: Claims Intake Team
last_reviewed: 2026-09-09
---

# Claim Search

Claim Search is the entry screen for the Claims Intake application. Claims staff
land here after signing in and use it to determine whether a reported injury
already has a claim on file. The screen accepts a claim number, claimant name,
date-of-injury range, or employer policy number, validates the combination
through `SAIF.Framework.Validation`, and calls the claims web service to return
matching claims into an `UltraWebGrid`. From the results the user opens an
existing claim, starts a new claim, or switches to claimant search.

## Entry conditions
- The user signs in to Claims Intake; `Default.aspx` redirects authenticated
  users to `Claims/ClaimSearch.aspx` as the application start page.
- The user selects **Search Claims** from the persistent site navigation on any
  Claims Intake screen.
- The user returns from Claim Detail using the **Back to results** link, which
  reposts to this screen with the previous criteria restored from session state.

## Fields

| Field | Control type | Purpose | Validation |
| --- | --- | --- | --- |
| `txtClaimNumber` | TextBox | Exact claim number lookup | Optional; when supplied must match 8 digits, enforced by `revClaimNumber` |
| `txtClaimantLastName` | TextBox | Claimant surname, partial match allowed | Optional; maximum 40 characters, minimum 2 characters when supplied |
| `txtClaimantFirstName` | TextBox | Claimant given name, partial match allowed | Optional; maximum 40 characters; ignored unless a last name is supplied |
| `txtPolicyNumber` | TextBox | Employer policy number filter | Optional; must match 7 digits, enforced by `revPolicyNumber` |
| `dtpInjuryFrom` | WebDateChooser | Start of date-of-injury range | Optional; must be a valid date not later than today |
| `dtpInjuryTo` | WebDateChooser | End of date-of-injury range | Optional; must be a valid date not earlier than `dtpInjuryFrom` |
| `ddlClaimStatus` | DropDownList | Restricts results to a claim status | Optional; defaults to `All`; bound from the claims web service status list |
| `btnSearch` | Button | Executes the search | Triggers page validation before the handler runs |
| `btnClear` | Button | Resets all criteria and the results grid | Causes no validation; `CausesValidation` is `False` |
| `grdResults` | UltraWebGrid | Displays matching claims | Not user-editable; read-only result display |

## Operations

| Operation | Trigger | Description | Delegates to |
| --- | --- | --- | --- |
| search-claims | `btnSearch` Click | Builds a criteria object from the entered fields, validates it, calls the claims web service, and binds the returned claim rows to `grdResults` | `ValidateSearchCriteria` in `SAIF.Framework.Validation`† |
| clear-criteria | `btnClear` Click | Clears every criteria control, empties the results grid, and removes the saved criteria from session state | — |
| open-claim | `grdResults` DblClick on a data row | Reads the claim number from the selected row and navigates to Claim Detail | — |
| page-results | `grdResults` PageIndexChanged | Re-runs the last search for the requested page and rebinds the grid | `ValidateSearchCriteria` in `SAIF.Framework.Validation`† |
| sort-results | `grdResults` SortColumn | Reorders the cached result set by the selected column and rebinds the grid | — |

## Business rules

| Rule ID | Rule | Enforcement | Source |
| --- | --- | --- | --- |
| [BR-SCR-001](../application/business-rules.md#br-scr-001-at-least-one-search-criterion-required) | At least one search criterion must be supplied before a search runs | `btnSearch_Click` calls `HasAnyCriteria` and shows `lblSearchError` when it returns `False` | `src/SAIF.Claims.Intake/Claims/ClaimSearch.aspx.vb:118` |
| [BR-SCR-002](../application/business-rules.md#br-scr-002-injury-date-range-must-be-ordered) | The date-of-injury range end must not precede the range start | `cvInjuryDateRange` custom validator, server method `cvInjuryDateRange_ServerValidate` | `src/SAIF.Claims.Intake/Claims/ClaimSearch.aspx.vb:186` |
| [BR-SCR-003](../application/business-rules.md#br-scr-003-claimant-first-name-requires-last-name) | A claimant first name is only accepted alongside a last name | `BuildSearchCriteria` discards `txtClaimantFirstName` when `txtClaimantLastName` is empty | `src/SAIF.Claims.Intake/Claims/ClaimSearch.aspx.vb:152` |
| [BR-APP-002](../application/business-rules.md#br-app-002-search-results-capped-at-250-claims) | A single search returns at most 250 claims | `SearchClaims` requests a 250-row maximum and `lblResultCap` warns the user when the cap is reached | `src/SAIF.Claims.Intake/Claims/ClaimSearch.aspx.vb:214` |
| [BR-APP-003](../application/business-rules.md#br-app-003-closed-claims-are-read-only) | Closed claims open in read-only mode | `grdResults_DblClick` appends `mode=readonly` to the Claim Detail query string when the row status is `Closed` | `src/SAIF.Claims.Intake/Claims/ClaimSearch.aspx.vb:268` |

## Infragistics components

| Control ID | Control type | SAIF wrapper | Infragistics base | Purpose |
| --- | --- | --- | --- | --- |
| `grdResults` | Data grid | `SaifResultsGrid` | `Infragistics.WebUI.UltraWebGrid.UltraWebGrid` | Displays matching claims with paging and column sorting |
| `dtpInjuryFrom` | Date picker | `SaifDateChooser` | `Infragistics.WebUI.WebSchedule.WebDateChooser` | Captures the start of the date-of-injury range |
| `dtpInjuryTo` | Date picker | `SaifDateChooser` | `Infragistics.WebUI.WebSchedule.WebDateChooser` | Captures the end of the date-of-injury range |
| `wtbSearchToolbar` | Toolbar | `SaifToolbar` | `Infragistics.WebUI.WebNavigator.UltraWebToolbar` | Hosts the Search, Clear, and New Claim commands above the criteria panel |

## Navigation

| Target | Trigger | Parameters |
| --- | --- | --- |
| [Claim Detail](claim-detail.md) | Double-click a row in `grdResults`, or click the claim number link in the row | `claimNumber`, and `mode=readonly` when the claim status is `Closed` |
| [New Claim](claim-new.md) | Click **New Claim** on `wtbSearchToolbar` | `policyNumber` when a policy number was entered in the criteria panel |
| [Claimant Search](claimant-search.md) | Click **Search by claimant** beneath the criteria panel | `lastName`, `firstName` carried over from the entered claimant fields |

## Screen flow diagram

```mermaid
flowchart TD
    A[Claim Search] -->|Double-click result row| B[Claim Detail]
    A -->|New Claim toolbar command| C[New Claim]
    A -->|Search by claimant| D[Claimant Search]
    B -->|Back to results| A
```

## API calls

| Endpoint | Method | Purpose |
| --- | --- | --- |
| `/ClaimsService/ClaimSearch.asmx/SearchClaims` | POST | Returns claims matching the supplied criteria, capped at 250 rows |
| `/ClaimsService/ClaimSearch.asmx/GetClaimStatusList` | POST | Supplies the status values bound to `ddlClaimStatus` on first load |
| `/ClaimsService/ClaimSearch.asmx/GetClaimSummary` | POST | Retrieves the summary row rendered in the results grid tooltip |

---

> [!NOTE]
> Statements marked with `*` are inferred from code patterns. Statements marked with `**` could not be verified from available source.

## Sources
- src/SAIF.Claims.Intake/Claims/ClaimSearch.aspx
- src/SAIF.Claims.Intake/Claims/ClaimSearch.aspx.vb
- src/SAIF.Claims.Intake/Claims/ClaimSearch.aspx.designer.vb
- src/SAIF.Claims.Intake/Common/SearchCriteria.vb
- src/SAIF.Claims.Intake/Web References/ClaimsService/Reference.vb
````