docs(requirements): split handler rows

Add explicit ring fields to derive_handler requirements and split handler parameter constraints without changing behavior.

req: derive_handler/001

req: derive_handler/002

req: derive_handler/003

req: derive_handler/004

req: derive_handler/005
This commit is contained in:
slhx agent
2026-06-25 17:52:36 +02:00
parent 82b1b29f1f
commit c7ca3aab9d
3 changed files with 10 additions and 7 deletions
+7 -4
View File
@@ -1110,16 +1110,16 @@ what a valid business email is. [north_star]
## derive_handler
### req: derive_handler/001
001 `#[hemx::handler]` validates: handle name exists in symbol table, params match form surface or `data-*` attributes, return type implements `IntoEffect`. Generate code registers the function in a static lookup table keyed by numeric handle id.
0 001 `#[hemx::handler]` validates handle name, params, and `IntoEffect` return type; generated code registers a static lookup entry keyed by numeric handle id.
### req: derive_handler/002
002 Handler param inference from `data-*` attributes: when a template declares `data-card-id="{card.id}"` on a node with `data-hemx-handle`, the handler may declare `card_id: CardId` as a parameter. hemx-build checks attribute → param name and type mapping.
0 002 Handler param inference from `data-*` attributes allows template `data-card-id="{card.id}"` to map to a `card_id: CardId` handler parameter checked by hemx-build.
### req: derive_handler/003
003 Handler parameters are inferred from four sources: `Form<T>`, `data-*` attributes on the triggering node, route params supplied by integration crates, and explicit app/context parameters. Missing or incompatible params are compile-time errors with source spans. hemx does not implement selector-based `hx-include`; shared params are represented by forms, hidden inputs, scoped context, or explicit `data-*` attributes.
0 003 Handler parameters are inferred from `Form<T>`, triggering-node `data-*` attributes, integration-supplied route params, and explicit app/context parameters.
### req: derive_handler/004
004 The common handler signature forms are plain Rust functions, synchronous or async:
0 004 The common handler signature forms are plain Rust functions, synchronous or async:
```rust
fn ping() -> impl IntoEffect
async fn add(app: State<App>, form: Form<NewTodo>) -> impl IntoEffect
@@ -1128,6 +1128,9 @@ async fn delete(app: State<App>, todo_id: TodoId) -> impl IntoEffect
```
`State<App>` is illustrative integration context; equivalent framework extractors or app references are adapter concerns. Form fields and `data-*` params parse through normal Rust `FromForm`/`FormValue`/`FromStr`-style traits, so domain newtypes remain user-authored. Handlers may return `impl IntoEffect` or `Result<impl IntoEffect, E>` for fallible database/domain work; `IntoEffect` values compose through tuples while `Result` paths preserve a typed error boundary (`IntoHandlerFailure` in the Axum adapter) for integrations to map failures to generated UI effects, toasts, events, or HTTP responses. Result-specific registry adapters are generated/integration internals; canonical app code uses the same `#[hemx::handler]` and `#[hemx::app]` authoring shape for plain and fallible handlers.
### req: derive_handler/005
0 005 Missing or incompatible handler params are compile-time errors with source spans; shared params use forms, hidden inputs, scoped context, or explicit `data-*` attributes, not selector-based `hx-include`.
---
## derive_app