docs(requirements): split convention rows
Add explicit ring fields to convention requirements and split UX convention constraints without changing behavior. req: convention/001 req: convention/002 req: convention/003 req: convention/004 req: convention/005 req: convention/006 req: convention/007 req: convention/008 req: convention/009 req: convention/010 req: convention/011 req: convention/012 req: convention/013 req: convention/014 req: convention/015 req: convention/016 req: convention/017
This commit is contained in:
slhx agent
@@ -64,7 +64,7 @@ Keep it stable. Prefer pointers to canonical sources over copied structure, file
|
||||
- The public component-reuse explanation lives in `docs/recipes/reusable-partials.md`; do not grow a client component framework to explain partial composition.
|
||||
- The stable public `.heml` authoring surface lives in `docs/hemplate-syntax.md`; Hemlate examples must use that real hemplate syntax, not Vue/Handlebars sketches. hemx-build consumes hemplate Surface facts and must not grow an independent `.heml` parser or CSS-path identity model. Plain CSS/SCSS owns appearance; generated class constants are ergonomic references, not a styling framework or behavior selector system. Generated resources, form/handle metadata, atoms, and event constants come from hemx-build facts, not hand-written app plumbing. Forms remain HTML-shaped, checked against user-authored Rust domain types, parsed through `FormValue`, and manipulated through generated form/control ids rather than selectors. Proc-macros stay local/side-effect-free while build.rs owns global codegen and hard build failures. req: boundary/001 req: boundary/002 req: boundary/003 req: boundary/004 req: surface/001 req: surface/002 req: surface/003 req: surface/004 req: surface/005 req: surface/006 req: surface/007 req: surface/008 req: surface/009 req: surface/010 req: codegen/001 req: codegen/003 req: codegen/004 req: codegen/005 req: codegen/006 req: form/001 req: form/004 req: form/007 req: form/008 req: form_effects/001 req: form_effects/002 req: form_effects/003 req: build/001 req: build/002 req: build/003 req: build/004 req: build/005 req: build/006 req: build/007 req: build/008 req: style/001 req: style/002 req: style/003 req: style/004 req: style/005 req: style/006
|
||||
- Optional `.heml` editor overlays must share authority with `hemx-build` diagnostics and `docs/hemplate-syntax.md`; `hemx-lsp` owns editor protocol glue for diagnostics/completion/hover and derive-known template facts, while VS Code/Cursor/Neovim keep normal HTML/tree-sitter tooling. Do not create a second template language, selector model, formatter, Rust type system, or custom editor framework. Cross-file template/handler references visible to build validation must fail at `cargo check` with useful spans; global completeness checks stay component-scoped unless caught at mount/tests. req: diagnostics/004 req: diagnostics/005 req: diagnostics/006 req: diagnostics/007 req: diagnostics/008 req: invariant/004 req: invariant/006 req: check/001 req: check/003
|
||||
- JS runtime changes must preserve root-scoped lookup, delegated listeners, postcard EffectBatch application, fail-closed request handling, transactional/recoverable failure behavior, root-scoped error outlets, and tiny pending/failure/trigger-timing conventions without selectors, handler-name parsing, VDOM, expressions, or per-node listeners. Runtime `.d.ts` types are developer convenience only, not core tooling authority. req: invariant/002 req: runtime/001 req: runtime/002 req: runtime/003 req: runtime/005 req: runtime/006 req: failure/001 req: failure/002 req: failure/003 req: failure/004 req: failure/005 req: failure/006 req: convention/001 req: convention/003 req: convention/005 req: convention/007 req: ts/001
|
||||
- JS runtime changes must preserve root-scoped lookup, delegated listeners, postcard EffectBatch application, fail-closed request handling, transactional/recoverable failure behavior, root-scoped error outlets, and tiny pending/failure/trigger-timing conventions without selectors, handler-name parsing, VDOM, expressions, or per-node listeners. Runtime `.d.ts` types are developer convenience only, not core tooling authority. req: invariant/002 req: runtime/001 req: runtime/002 req: runtime/003 req: runtime/005 req: runtime/006 req: failure/001 req: failure/002 req: failure/003 req: failure/004 req: failure/005 req: failure/006 req: convention/001 req: convention/002 req: convention/003 req: convention/004 req: convention/005 req: convention/006 req: convention/007 req: convention/008 req: convention/009 req: convention/010 req: convention/011 req: convention/012 req: convention/013 req: convention/014 req: convention/015 req: convention/016 req: convention/017 req: ts/001
|
||||
- Opaque island JavaScript is a leaf adapter for high-frequency local behavior only; client-local handlers keep the server-handler shape while `hemx-wasm` owns concrete opt-in syntax. Use native events/generated helpers at the boundary and do not introduce a component runtime, client state graph, VDOM, selector interop, or second UI model. req: canonical_authoring/017 req: client_local/001 req: client_local/003 req: client_local/004 req: interop/001 req: interop/002 req: interop/003 req: interop/006 req: interop/007 req: interop/008 req: interop/009 req: interop/010 req: interop/011 req: interop/012
|
||||
- Host capability adapters must stay at the `hemx-host` boundary: typed capabilities use fire/request/stream/schedule shapes; adapters may call host APIs and return host events, but they must not mutate DOM or own app/domain state. req: host/001 req: host/002
|
||||
- Local/offline app behavior should be commands/events/projections; do not add `hemx-local`, stored DOM patches, stored `EffectBatch` truth, or a core client state graph without a proven reusable contract. Atoms are explicit addressable/bootstrap/sync resources, not the default state container or a reactive framework. Replay, reconciliation, export, and deletion rules stay explicit product decisions, and exemplars should show UI effects as app-state output. The local-first multiplayer kanban remains an advanced north-star integration milestone, not beginner/API surface scope. req: canonical_authoring/018 req: canonical_authoring/019 req: state/001 req: state/002 req: state/003 req: state/004 req: state/005 req: state/006 req: state/007 req: local/001 req: local/002 req: local/003 req: local/004 req: milestone/001 req: milestone/002 req: milestone/003
|
||||
|
||||
+33
-9
@@ -1178,31 +1178,55 @@ async fn delete(app: State<App>, todo_id: TodoId) -> impl IntoEffect
|
||||
## convention
|
||||
|
||||
### req: convention/001
|
||||
001 hemx-axum and the JS runtime support common UX conventions as attributes, not core effects: `data-hemx-pending-class`, `data-hemx-indicator`, `data-hemx-confirm`, `data-hemx-debounce`, `data-hemx-delay`, `data-hemx-throttle`, `data-hemx-every`, `data-hemx-interval`, `data-hemx-revealed`, `data-hemx-disable-while-pending`, `data-hemx-policy`, and `data-hemx-on`. These are orthogonal to the core effect algebra.
|
||||
0 001 hemx-axum and the JS runtime support common UX conventions as attributes, not core effects; these remain orthogonal to the core effect algebra.
|
||||
|
||||
### req: convention/002
|
||||
002 Default event triggers: `submit` for forms, `click` for buttons and links. `data-hemx-on` overrides the default for the runtime-supported delegated events: `click`, `submit`, `input`, `change`, `dragstart`, `dragover`, and `drop`. Unsupported static event names are build errors.
|
||||
0 002 Default event triggers are `submit` for forms and `click` for buttons and links; `data-hemx-on` overrides the default.
|
||||
|
||||
### req: convention/003
|
||||
003 `data-hemx-debounce`, `data-hemx-delay`, and `data-hemx-throttle` support simple millisecond values. No trigger mini-language in core.
|
||||
0 003 `data-hemx-debounce`, `data-hemx-delay`, and `data-hemx-throttle` support simple millisecond values. No trigger mini-language in core.
|
||||
|
||||
### req: convention/004
|
||||
004 `data-hemx-confirm` dispatches a native `confirm()` before handler dispatch. Static empty confirmation messages are build errors because they silently disable the guard in browsers. Custom confirm UI belongs to integration crates.
|
||||
0 004 `data-hemx-confirm` dispatches a native `confirm()` before handler dispatch.
|
||||
|
||||
### req: convention/005
|
||||
005 `data-hemx-every` and `data-hemx-interval` dispatch a handle at a fixed interval while the element remains in the document. `data-hemx-revealed` dispatches once when the element enters view, with an immediate fallback when `IntersectionObserver` is unavailable. Duplicate timers/observers per root are avoided.
|
||||
0 005 `data-hemx-every` and `data-hemx-interval` dispatch a handle at a fixed interval while the element remains in the document.
|
||||
|
||||
### req: convention/006
|
||||
006 Request concurrency policy (`latest`, `queue`, `drop`, `parallel`) may be declared per handle with `data-hemx-policy`. Default for debounced/input handlers is `latest`; default for form submit is `drop` while pending. Stale EffectBatches from superseded requests must not be applied.
|
||||
0 006 Request concurrency policy (`latest`, `queue`, `drop`, `parallel`) may be declared per handle with `data-hemx-policy`.
|
||||
|
||||
### req: convention/007
|
||||
007 Pending indicators are cosmetic only. The runtime toggles pending classes, `aria-busy`, indicator visibility, and disabled controls around request/effect execution; handler semantics are unchanged.
|
||||
0 007 Pending indicators are cosmetic only. The runtime toggles pending classes, `aria-busy`, indicator visibility, and disabled controls around request/effect execution; handler semantics are unchanged.
|
||||
|
||||
### req: convention/008
|
||||
008 `data-hemx-disable-while-pending` disables the triggering form controls or button while the request is active and restores them afterward.
|
||||
0 008 `data-hemx-disable-while-pending` disables the triggering form controls or button while the request is active and restores them afterward.
|
||||
|
||||
### req: convention/009
|
||||
009 Unknown `data-hemx-*` authoring attributes are build errors with a suggested fix. hemx-owned attributes are a checked contract, not a silent extension namespace; opaque/integration islands should use explicit allowed attributes or their own non-hemx `data-*` names.
|
||||
0 009 Unknown `data-hemx-*` authoring attributes are build errors with a suggested fix; opaque/integration islands must use explicit allowed attributes or their own non-hemx `data-*` names.
|
||||
|
||||
### req: convention/010
|
||||
0 010 Supported cosmetic convention attributes include `data-hemx-pending-class`, `data-hemx-indicator`, `data-hemx-confirm`, and `data-hemx-disable-while-pending`.
|
||||
|
||||
### req: convention/011
|
||||
0 011 Supported timing/trigger convention attributes include `data-hemx-debounce`, `data-hemx-delay`, `data-hemx-throttle`, `data-hemx-every`, `data-hemx-interval`, `data-hemx-revealed`, `data-hemx-policy`, and `data-hemx-on`.
|
||||
|
||||
### req: convention/012
|
||||
0 012 Runtime-supported delegated events are `click`, `submit`, `input`, `change`, `dragstart`, `dragover`, and `drop`; unsupported static event names are build errors.
|
||||
|
||||
### req: convention/013
|
||||
0 013 Static empty confirmation messages are build errors: they silently disable the guard in browsers. Custom confirm UI belongs to integration crates.
|
||||
|
||||
### req: convention/014
|
||||
0 014 `data-hemx-revealed` dispatches once when the element enters view, with an immediate fallback when `IntersectionObserver` is unavailable.
|
||||
|
||||
### req: convention/015
|
||||
0 015 Duplicate timers/observers per root are avoided.
|
||||
|
||||
### req: convention/016
|
||||
0 016 Default concurrency policy for debounced/input handlers is `latest`; default for form submit is `drop` while pending.
|
||||
|
||||
### req: convention/017
|
||||
0 017 Stale EffectBatches from superseded requests must not be applied.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user