docs: document caller callbacks from ComponentState

ZE
6d ago
+171-0

A ComponentState handler can return an event for a caller-provided EventHandler. This adds a tested recipe that stores the callback target on each generated class and keeps the count in client state. Increment and decrement notify the caller when the resulting count is above ten. Related to #3711.

The unit test executes the exact documentation example. It checks threshold boundaries, omitted callbacks, separate targets, rendered handler binding, state-field separation and normalized event payloads. This uses existing event composition and adds no framework API or event-loop change.

Validation: all 5 tests in the existing focused unit module passed with the normal repository conftest. The unchanged pre-commit configuration passed for all 3 changed files, including Ruff, codespell, update-pyi-files, Pyright and ty. Browser dispatch and the full unit suite were not run.

AI assistance was used for the documentation, tests and local review. The listed checks were run locally. An independent adversarial review checked the complete patch.

Reward context: #3711 has a historical unpriced bounty promise. This PR documents and tests an existing callback-composition recipe related to that request. Please confirm whether this limited recipe qualifies under that offer and what the current reward terms are. No amount, acceptance or payment is assumed.