# Goal

Build an incident-report **validation demo** with a working browser/game/server round trip.
It intentionally does not store reports or send dispatch alerts; successful validation says so.
All six required files are included, with no missing `config.lua` or stylesheet.

## Overview

[Download the complete NUI example](https://qbcore.net/examples/docs-nui-form.zip).
The ZIP is generated from the repository's `examples/docs-nui-form` source during `pnpm build`;
it is not a separately maintained copy. Extract the `docs-nui-form` folder into `resources/[local]`.

**Test boundary:** source-reviewed and mock-tested. Actual FiveM focus, keyboard interaction and
resource-restart acceptance must still be run on your staging server. No in-game certification is implied.

## Resource Layout

```text
docs-nui-form/
├── fxmanifest.lua
├── client.lua
├── server.lua
└── html/
    ├── index.html
    ├── styles.css
    └── script.js
```

## Step-by-Step Implementation

### 1. Define the resource manifest

The included manifest explicitly declares every browser file and the core dependency:

```lua
fx_version 'cerulean'
game 'gta5'
dependency 'qb-core'
ui_page 'html/index.html'
files { 'html/index.html', 'html/styles.css', 'html/script.js' }
client_script 'client.lua'
server_script 'server.lua'
```

Add `ensure docs-nui-form` after core in `server.cfg`. Use an isolated development server with an
already working QBCore character login. This example adds no SQL and requires no phone/dispatch resource.

### 2. Build the NUI form

`html/index.html` provides labelled citizen-ID, category and description fields, a submit button,
a close button and a status region. The panel starts hidden. `styles.css` explicitly preserves
`[hidden]`, so a layout rule cannot accidentally show the form at resource startup.

The example accepts a subject ID as text; it neither verifies that the subject exists nor exposes
that character's private data. Do not describe its successful reply as a saved police report.

### 3. Send form data to the server

`html/script.js` posts JSON to `https://${GetParentResourceName()}/submit-incident` inside FiveM NUI.
It checks HTTP failure, bounds waiting with a browser timeout and prevents duplicate submits while
one browser request is pending. The game resource name is obtained from the NUI environment, not a
hardcoded host.

Closing or reopening advances a UI generation counter. A late result from a previous form session
cannot overwrite the current status. Opening the HTML in an ordinary browser does not provide the
FiveM bridge; do not replace it with an invented browser implementation of a game native.

### 4. Handle UI state on the client

`client.lua` initializes `QBCore` with `GetCoreObject`, registers `/report`, and handles both NUI
routes: `close` and `submit-incident`. Open/close messages have matching browser listeners.
Close, character unload and resource stop release focus and hide the UI.

There are two callbacks, not one: the browser's NUI callback and the client/server QBCore callback.
The client completes the NUI callback on rejection, close, server response or timeout. It sends only
one request at a time through the named QBCore callback. At this core revision, pending callbacks are
keyed by name. After a timeout the client waits for the late server reply rather than overwriting
that registry with another request of the same name. A token check rejects mismatched responses.

### 5. Validate and process server-side

`server.lua` looks up the actual caller, checks the outer payload type, rate-limits submissions and
validates each string before indexing or calling string methods. Category must be on the server's
allowlist. Citizen IDs are restricted to 4–32 letters/digits/underscores/hyphens; details must contain
non-whitespace text and fit the 500-byte limit. The HTML character limit does not replace the server
byte limit for multibyte text.

Every rejection and the successful demonstration reply invokes `cb`. The example does not print
report contents into server logs. Cooldown state is cleared on character unload/disconnection.

## Testing Checklist

| Action | Expected result |
| --- | --- |
| Start the resource while logged in; run `/report` | Form opens, keyboard/mouse focus belongs to NUI |
| Submit a valid report | Explicit "demo only" success; no database/dispatch claim |
| Submit malformed objects or unknown categories in staging | Server rejection, no Lua type error |
| Submit twice rapidly | Busy or rate-limit response, not parallel callback replacement |
| Close/Escape during a pending request | UI closes; late reply cannot overwrite a reopened session |
| Delay the server response beyond the timeout | Browser receives an error; client does not launch another same-name request |
| Logout or restart the resource with the form open | UI hides and game focus returns |
| Rename the resource folder | Browser route still uses the runtime resource name |

Repository maintainers can rebuild archives with `node scripts/build-tutorial-examples.mjs` and run
the documented Lua harness in `scripts/examples/test-complete-tutorials.lua`.

## Troubleshooting

**UI stays hidden:** inspect F8 and the NUI console; confirm the command ran after login, the manifest
lists all HTML assets, and the browser receives an `open` message.

**Callback never returns:** check both route names and the QBCore callback name. A browser timeout
does not prove the server operation failed. This demo blocks another same-name request until the
first server response returns; restart only this example in staging after investigating the cause.

**Focus stuck:** test Close/Escape, character unload and resource stop. The cleanup path must run
`SetNuiFocus(false, false)` as well as hiding the browser panel.

## Next Steps

- [Safe server events](/docs/security/safe-server-events): authorization before adding storage or dispatch.
- [PlayerData](/docs/core/player-data): lifecycle and correct update payloads.
- [Debugging](/docs/development/debugging): inspect browser, client and server separately.

## Sources

- [Cfx.re NUI callbacks](https://docs.fivem.net/docs/scripting-manual/nui-development/nui-callbacks/)
- [Pinned core callback dispatch](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/events.lua)
- [Pinned client callback registry](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/client/events.lua)
