tmk241/hemx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api): hide render compatibility aliases

Browse Source 
Keep render_html/lower_html available for explicit compatibility while generated/public docs steer authors to render/lower and generated resource commands.

req: dx/006
This commit is contained in:
slhx agent
2026-06-02 03:18:53 +02:00
parent 73836f3742
commit 9fd614f86d
3 changed files with 8 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
REQUIREMENTS.md
+1 -1
View File
@@ -76,7 +76,7 @@ slhx competes with React by making frontend frameworks unnecessary for most apps
005 Error messages must explain fixes in author language, not internal language. Say “add `h-key="todo.id"` to this `h-for`”, not “missing ScopeKey for ResourceRef”.
### req: dx/006
006 Generated resource commands are the preferred authoring API: `ui::put(slots::todo_list, &view)`, `ui::append(slots::card, key, &view)`, `slots::count.text(42)`, `atoms::user.set(user)`. The public facade exposes `render(view)` for trusted hemplate-to-`SafeHtml` page and fragment composition; generated view modules expose lower-aware `render(view)`, `put(slot, view)`, `append/prepend/replace(keyed_slot, key, view)`, `static_fragment(include_str!(...))` for prototype/static `.heml` fragments that need generated resource lowering as `SafeHtml`, plus `lower(html)` for callers that need the lowered string. `render_html(view)` and `lower_html(html)` remain explicit compatibility aliases and are not beginner-prelude exports. The beginner prelude should not expose lower-level slot render shortcuts that bypass generated lowering. These return `impl IntoEffect`, `SafeHtml`, or lowered HTML at the boundary. Raw `Effect` constructors, opcodes, and `EffectWriter` remain low-level. [north_star]
006 Generated resource commands are the preferred authoring API: `ui::put(slots::todo_list, &view)`, `ui::append(slots::card, key, &view)`, `slots::count.text(42)`, `atoms::user.set(user)`. The public facade exposes `render(view)` for trusted hemplate-to-`SafeHtml` page and fragment composition; generated view modules expose lower-aware `render(view)`, `put(slot, view)`, `append/prepend/replace(keyed_slot, key, view)`, `static_fragment(include_str!(...))` for prototype/static `.heml` fragments that need generated resource lowering as `SafeHtml`, plus `lower(html)` for callers that need the lowered string. `render_html(view)` and `lower_html(html)` remain doc-hidden compatibility aliases and are not beginner-prelude exports. The beginner prelude should not expose lower-level slot render shortcuts that bypass generated lowering. These return `impl IntoEffect`, `SafeHtml`, or lowered HTML at the boundary. Raw `Effect` constructors, opcodes, and `EffectWriter` remain low-level. [north_star]
### req: dx/007
007 Tuple composition of `IntoEffect` is the canonical batch syntax: `(a, b, c)` implements `IntoEffect` up to arity 12. `Effect::batch((...))` is available but not required for the happy path.
slhx-build/src/lib.rs
+6 -4
View File
@@ -524,6 +524,7 @@ impl Resources {
}
out.push_str(&format!("__slhx_lower_html(html.as_ref(), &{table_name})\n"));
out.push_str(&format!("{pad}}}\n\n"));
out.push_str(&format!("{pad}#[doc(hidden)]\n"));
out.push_str(&format!("{pad}pub fn lower_html(html: impl ::std::convert::AsRef<str>) -> ::std::string::String {{ lower(html) }}\n\n"));
out.push_str(&format!("{pad}pub fn static_fragment(html: &'static str) -> ::slhx::SafeHtml {{\n"));
out.push_str(&format!("{pad} ::slhx::SafeHtml::trusted(lower(html))\n"));
@@ -533,6 +534,7 @@ impl Resources {
out.push_str(&format!("{pad} ::hemplate::Hemplate::render_into(view, &mut html).expect(\"slhx hemplate view renders\");\n"));
out.push_str(&format!("{pad} ::slhx::SafeHtml::trusted(lower(html))\n"));
out.push_str(&format!("{pad}}}\n\n"));
out.push_str(&format!("{pad}#[doc(hidden)]\n"));
out.push_str(&format!("{pad}pub fn render_html(view: &impl ::hemplate::Hemplate) -> ::slhx::SafeHtml {{ render(view) }}\n\n"));
out.push_str(&format!("{pad}pub fn put<T>(slot: ::slhx::Slot<T>, view: &impl ::hemplate::Hemplate) -> impl ::slhx::IntoEffect {{\n"));
out.push_str(&format!("{pad} slot.html(render(view))\n"));
@@ -1324,10 +1326,10 @@ mod tests {
assert!(generated.contains("pub mod todo"));
assert!(generated.contains("pub const ALL_IDS"));
assert!(generated.contains("pub fn lower(html: impl ::std::convert::AsRef<str>) -> ::std::string::String"));
assert!(generated.contains("pub fn lower_html"));
assert!(generated.contains("#[doc(hidden)]\npub fn lower_html"));
assert!(generated.contains("pub fn static_fragment(html: &'static str) -> ::slhx::SafeHtml"));
assert!(generated.contains("pub fn render(view: &impl ::hemplate::Hemplate) -> ::slhx::SafeHtml"));
assert!(generated.contains("pub fn render_html(view: &impl ::hemplate::Hemplate) -> ::slhx::SafeHtml"));
assert!(generated.contains("#[doc(hidden)]\npub fn render_html(view: &impl ::hemplate::Hemplate) -> ::slhx::SafeHtml"));
assert!(generated.contains("pub fn put<T>(slot: ::slhx::Slot<T>, view: &impl ::hemplate::Hemplate) -> impl ::slhx::IntoEffect"));
assert!(generated.contains("pub fn append<K, T>(slot: ::slhx::KeyedSlot<K, T>, key: K, view: &impl ::hemplate::Hemplate) -> impl ::slhx::IntoEffect"));
assert!(generated.contains("pub fn prepend<K, T>(slot: ::slhx::KeyedSlot<K, T>, key: K, view: &impl ::hemplate::Hemplate) -> impl ::slhx::IntoEffect"));
@@ -1397,10 +1399,10 @@ mod tests {
assert!(!generated.contains("\n#[allow(non_upper_case_globals)]\npub mod components"));
assert!(!generated.contains("\n#[allow(non_upper_case_globals)]\npub mod slots"));
assert!(generated.contains("\npub fn lower(html: impl ::std::convert::AsRef<str>) -> ::std::string::String"));
assert!(generated.contains("\npub fn lower_html"));
assert!(generated.contains("\n#[doc(hidden)]\npub fn lower_html"));
assert!(generated.contains("\npub fn static_fragment(html: &'static str) -> ::slhx::SafeHtml"));
assert!(generated.contains("\npub fn render(view: &impl ::hemplate::Hemplate) -> ::slhx::SafeHtml"));
assert!(generated.contains("\npub fn render_html(view: &impl ::hemplate::Hemplate) -> ::slhx::SafeHtml"));
assert!(generated.contains("\n#[doc(hidden)]\npub fn render_html(view: &impl ::hemplate::Hemplate) -> ::slhx::SafeHtml"));
assert!(generated.contains("\npub fn put<T>(slot: ::slhx::Slot<T>, view: &impl ::hemplate::Hemplate) -> impl ::slhx::IntoEffect"));
assert!(generated.contains("\npub fn append<K, T>(slot: ::slhx::KeyedSlot<K, T>, key: K, view: &impl ::hemplate::Hemplate) -> impl ::slhx::IntoEffect"));
assert!(generated.contains("pub mod todo"));
slhx/src/lib.rs
+1
View File
@@ -13,6 +13,7 @@ pub fn render(view: &impl hemplate::Hemplate) -> SafeHtml {
SafeHtml::trusted(html)
}
#[doc(hidden)]
pub fn render_html(view: &impl hemplate::Hemplate) -> SafeHtml {
render(view)
}