docs(requirements): tighten component rows

Add explicit northstar ring fields to component requirements, split the missing-handler fallback, and shorten overlong macro rows without changing behavior.

req: component/001

req: component/002

req: component/003

req: component/004

req: component/005

req: component/006

req: component/007
This commit is contained in:
slhx agent
2026-06-25 14:57:38 +02:00
parent 1a24dff507
commit a9f5fcb2be
2 changed files with 10 additions and 7 deletions
+1 -1
View File
@@ -57,7 +57,7 @@ Keep it stable. Prefer pointers to canonical sources over copied structure, file
- Use the same Workout command surface for tests, production build, and mobile release: `cargo run -p hemx-xtask -- workout test`, `cargo run -p hemx-xtask -- workout build`, `HEMX_WORKOUT_ORIGIN=https://workout.example.com cargo run -p hemx-xtask -- workout mobile-release`, and `HEMX_WORKOUT_ORIGIN=https://workout.example.com cargo run -p hemx-xtask -- workout mobile-verify`; Android/iOS SDKs, store submission targets, and signing remain external blockers, not repo-owned secrets. req: examples/006 req: examples/011
- hemx core stays small: effects, typed ids, registries, and wire schema only; keep features in core only when they fit typed resources plus EffectBatch ops. req: laws/001
- Routing, auth, sessions, transport, transitions, sync, and storage belong in integration/user crates.
- Public examples and beginner APIs should use templates plus Rust, generated resources, and `IntoEffect`, not atoms, raw ids, selectors, wire formats, runtime opcodes, manual registries, or raw effect constructors; keep advanced layers out of starters. req: canonical_authoring/001 req: canonical_authoring/004 req: canonical_authoring/006 req: canonical_authoring/010 req: canonical_authoring/015 req: dx/001 req: dx/002 req: dx/010 req: progressive_disclosure/001 req: progressive_disclosure/002 req: progressive_disclosure/003
- Public examples and beginner APIs should use templates plus Rust, generated component APIs, resources, and `IntoEffect`, not atoms, raw ids, selectors, wire formats, runtime opcodes, manual registries, `$OUT_DIR` includes, or raw effect constructors; keep advanced layers out of starters. req: canonical_authoring/001 req: canonical_authoring/004 req: canonical_authoring/006 req: canonical_authoring/010 req: canonical_authoring/015 req: dx/001 req: dx/002 req: dx/010 req: component/003 req: component/004 req: progressive_disclosure/001 req: progressive_disclosure/002 req: progressive_disclosure/003
- Typed partial swaps should stay expressed as generated target plus rendered partial plus swap kind, not selector-driven rerendering; HTTP, page navigation, push, and island behavior adapt around that loop, and docs should layer new primitives progressively. req: canonical_authoring/002 req: canonical_authoring/014 req: modes/001 req: progressive_disclosure/004 req: page_swap/001 req: page_swap/002 req: page_swap/003
- `examples/html_examples` is the copy-paste HTML pattern gallery for htmx-style examples; keep exact htmx URL slugs visible while translating behavior to boring `.heml`, generated resources, and server-owned Rust state, not HTMX syntax or selector targeting. Boost containers enhance same-origin descendants only and preserve native external/download/new-tab behavior. req: htmx_equivalents/001 req: htmx_equivalents/003 req: htmx_equivalents/005 req: examples/007 req: page_swap/007 req: page_swap/008
- Use `cargo run -p hemx-xtask -- app new PATH` for the generic page/form/keyed-row/notice starter, and `cargo run -p hemx-xtask -- app new --mobile PATH` for the phone-first starter with host capabilities, recovery truth, and release-kit commands; do not treat it as a mobile framework or store-submission bot. req: ceremony/005 req: ceremony/006 req: ceremony/007
+9 -6
View File
@@ -252,24 +252,27 @@ client app state framework.
## component
### req: component/001
001 The primary authoring unit is a hemplate component plus adjacent Rust handlers. A component owns a template root, generated slots, generated handles, generated form checks, and source spans.
0 001 The primary authoring unit is a hemplate component plus adjacent Rust handlers. A component owns a template root, generated slots, generated handles, generated form checks, and source spans. [north_star]
### req: component/002
002 hemx supports colocated layout: `todo_list.heml` beside `todo_list.rs`, with generated APIs namespaced by component to avoid global symbol soup.
0 002 hemx supports colocated layout: `todo_list.heml` beside `todo_list.rs`, with generated APIs namespaced by component to avoid global symbol soup. [north_star]
### req: component/003
003 Generated APIs are component-namespaced by default:
0 003 Generated APIs are component-namespaced by default. [north_star]
`ui::todo_list::todo_row`, `ui::todo_list::create`, `ui::todo_list::new_todo`, and `ui::todo_list::COMPONENT` as a checked `ComponentRef`.
Category modules such as `targets`, `handles`, and `forms` remain available for organization/compatibility, while raw slot constants live under `advanced::slots`; global exports (`ui::slots::*`, `ui::handles::*`, `ui::components::*`) are opt-in only.
### req: component/004
004 `#[hemx::surface]` bridges generated code into a user module. Users write `#[hemx::surface] mod ui {}` instead of `include!(concat!(env!("OUT_DIR"), ...))`. hemx-build emits `hemx.generated.rs` which the macro expands in place. No direct `$OUT_DIR` includes in user-authored source.
0 004 `#[hemx::surface]` bridges generated code into a user module. Users write `#[hemx::surface] mod ui {}` instead of direct `$OUT_DIR` includes; hemx-build emits `hemx.generated.rs` for the macro to expand in place. [north_star]
### req: component/005
005 An optional `#[hemx::component]` macro may validate that every handle declared in the template Surface has a corresponding `#[hemx::handler]` within the annotated module. This is the only macro with cross-handler visibility inside a single module; it remains strictly local. Missing handlers without `#[hemx::component]` are caught at app mount or test time, not `cargo check`.
0 005 Optional `#[hemx::component]` validates that each template Surface handle has a corresponding `#[hemx::handler]` within the annotated module. It is strictly module-local, with cross-handler visibility only inside that module. [north_star]
### req: component/007
0 007 Missing handlers without `#[hemx::component]` are caught at app mount or test time, not `cargo check`. [north_star]
### req: component/006
006 `#[derive(Hemplate)]` structs are natural component boundaries. hemx_build discovers them automatically; no additional configuration is required for most apps.
0 006 `#[derive(Hemplate)]` structs are natural component boundaries. hemx_build discovers them automatically; no additional configuration is required for most apps. [north_star]
---