diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md index 7663d69..5798e43 100644 --- a/REQUIREMENTS.md +++ b/REQUIREMENTS.md @@ -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. diff --git a/slhx-build/src/lib.rs b/slhx-build/src/lib.rs index 3ae80b4..dd08ac1 100644 --- a/slhx-build/src/lib.rs +++ b/slhx-build/src/lib.rs @@ -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) -> ::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(slot: ::slhx::Slot, 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) -> ::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(slot: ::slhx::Slot, view: &impl ::hemplate::Hemplate) -> impl ::slhx::IntoEffect")); assert!(generated.contains("pub fn append(slot: ::slhx::KeyedSlot, key: K, view: &impl ::hemplate::Hemplate) -> impl ::slhx::IntoEffect")); assert!(generated.contains("pub fn prepend(slot: ::slhx::KeyedSlot, 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) -> ::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(slot: ::slhx::Slot, view: &impl ::hemplate::Hemplate) -> impl ::slhx::IntoEffect")); assert!(generated.contains("\npub fn append(slot: ::slhx::KeyedSlot, key: K, view: &impl ::hemplate::Hemplate) -> impl ::slhx::IntoEffect")); assert!(generated.contains("pub mod todo")); diff --git a/slhx/src/lib.rs b/slhx/src/lib.rs index 3faa53f..64eac16 100644 --- a/slhx/src/lib.rs +++ b/slhx/src/lib.rs @@ -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) }