Skip to main content

rustango_cms/page_builder/
dyn_block.rs

1//! Dyn blocks — UI-defined field groups that flow through the
2//! existing [`Block`] machinery without inventory
3//! registration.
4//!
5//! A [`DynBlockDef`] is compiled from a schema/component
6//! [`GroupDef`] and **implements the
7//! `Block` trait**, so the admin stream editor (`render_block_inline`), the
8//! public renderer (`default_render`), and version migration all treat it
9//! exactly like a code block. The trait wants `&'static str` names — dyn
10//! defs intern theirs through a leak-once cache (bounded by the distinct
11//! slugs/labels edited over a process lifetime; precedent:
12//! `block/registry.rs` uses `Box::leak` for diagnostics).
13//!
14//! Resolution is an explicit **overlay**: a per-request
15//! [`DynBlockSet`] (loaded from the tenant's published schema) is checked
16//! before the inventory registry. No global state, tenant-safe.
17
18use std::collections::{HashMap, HashSet};
19use std::sync::{Arc, Mutex, OnceLock, PoisonError};
20
21use serde_json::Value;
22
23use crate::block::{Block, BlockError, BlockField, BlockRenderCtx};
24use crate::page_builder::schema::{FieldNode, GroupDef, Node};
25
26/// Intern a string into the process-lifetime pool. Each distinct string
27/// leaks exactly once; repeat calls return the cached `&'static str`.
28/// Shared with [`crate::page_builder::db_type`] so UI-created page
29/// types can hand the trait its required `&'static str`s from DB rows.
30pub(crate) fn intern(s: &str) -> &'static str {
31    static POOL: OnceLock<Mutex<HashSet<&'static str>>> = OnceLock::new();
32    let mut pool = POOL
33        .get_or_init(|| Mutex::new(HashSet::new()))
34        .lock()
35        .unwrap_or_else(PoisonError::into_inner);
36    if let Some(existing) = pool.get(s) {
37        return existing;
38    }
39    let leaked: &'static str = Box::leak(s.to_owned().into_boxed_str());
40    pool.insert(leaked);
41    leaked
42}
43
44/// The per-request set of UI-defined block types, keyed by type name
45/// (`r_<key>` repeater items, zone-local group keys, `c_<slug>`
46/// components). Loaded from the published schema; passed by reference
47/// through [`BlockRenderCtx::dyn_blocks`] and the `_with` editor variants.
48pub type DynBlockSet = HashMap<String, Arc<DynBlockDef>>;
49
50/// A UI-defined block: shape resolved from the DB at compile time, then
51/// behaviorally identical to a code block.
52#[derive(Debug)]
53pub struct DynBlockDef {
54    type_name: &'static str,
55    verbose_name: &'static str,
56    icon: Option<&'static str>,
57    description: Option<&'static str>,
58    label_format: Option<&'static str>,
59    fields: Vec<BlockField>,
60    version: u32,
61}
62
63impl DynBlockDef {
64    /// Build from a schema/component group definition. `version` is the
65    /// owning schema's (zone groups / repeater items) or component's
66    /// version — stamped into stored entries for lazy upgrade.
67    #[must_use]
68    pub fn from_group(type_name: &str, def: &GroupDef, version: u32) -> Self {
69        let label = if def.label.is_empty() {
70            &def.key
71        } else {
72            &def.label
73        };
74        Self {
75            type_name: intern(type_name),
76            verbose_name: intern(label),
77            icon: def.icon.as_deref().map(intern),
78            description: def.description.as_deref().map(intern),
79            label_format: def.label_format.as_deref().map(intern),
80            fields: children_to_block_fields(&def.children),
81            version,
82        }
83    }
84}
85
86/// Flatten a group's children (fields + rows) into sequential
87/// [`BlockField`]s — the block editor stacks fields vertically, so row
88/// layout inside stream items degrades to source order in v1.
89pub(crate) fn children_to_block_fields(children: &[Node]) -> Vec<BlockField> {
90    let mut out = Vec::new();
91    for node in children {
92        match node {
93            Node::Field(f) => out.push(field_to_block_field(f)),
94            Node::Row(row) => {
95                for child in &row.children {
96                    if let Node::Field(f) = child {
97                        out.push(field_to_block_field(f));
98                    }
99                }
100            }
101            // validate() rejects anything else inside a group def.
102            _ => {}
103        }
104    }
105    out
106}
107
108fn field_to_block_field(f: &FieldNode) -> BlockField {
109    let mut meta = crate::block::BlockFieldMeta::none();
110    meta.min_length = f.min_length;
111    meta.max_length = f.max_length;
112    if !f.pattern.is_empty() {
113        meta.pattern = Some(f.pattern.clone());
114    }
115    meta.min_value = f.min;
116    meta.max_value = f.max;
117    if !f.default_value.is_empty() {
118        meta.default_value = Some(f.default_value.clone());
119    }
120    BlockField::Widget {
121        name: f.key.clone(),
122        label: if f.label.is_empty() {
123            f.key.clone()
124        } else {
125            f.label.clone()
126        },
127        widget: f.widget,
128        options: f
129            .options
130            .iter()
131            .map(|c| (c.value.clone(), c.label.clone()))
132            .collect(),
133        help: if f.help.is_empty() {
134            None
135        } else {
136            Some(f.help.clone())
137        },
138        required: f.required,
139        meta,
140    }
141}
142
143impl Block for DynBlockDef {
144    fn type_name(&self) -> &'static str {
145        self.type_name
146    }
147    fn verbose_name(&self) -> &'static str {
148        self.verbose_name
149    }
150    fn fields(&self) -> Vec<BlockField> {
151        self.fields.clone()
152    }
153    fn icon(&self) -> Option<&'static str> {
154        self.icon
155    }
156    fn group(&self) -> Option<&'static str> {
157        Some("Page sections")
158    }
159    fn description(&self) -> Option<&'static str> {
160        self.description
161    }
162    fn label_format(&self) -> Option<&'static str> {
163        self.label_format
164    }
165    fn version(&self) -> u32 {
166        self.version
167    }
168
169    /// Host `blocks/<type_name>.html` wins when present; otherwise a
170    /// generic Rust-side walker renders the group's fields — so a
171    /// UI-defined group always renders without any template authoring.
172    fn render(&self, value: &Value, ctx: &BlockRenderCtx<'_>) -> Result<String, BlockError> {
173        let host_template = format!("blocks/{}.html", self.type_name);
174        if ctx.tera.get_template_names().any(|n| n == host_template) {
175            return crate::block::render::default_render(self, value, ctx);
176        }
177        Ok(generic_render(self, value, ctx))
178    }
179}
180
181/// A block field as the [`crate::widget::Widget`] the value renderer reads.
182fn as_widget(
183    name: &str,
184    label: &str,
185    kind: crate::widget::WidgetKind,
186    options: &[(String, String)],
187) -> crate::widget::Widget {
188    crate::widget::Widget::new(kind, name, label).with_options(options.iter().cloned())
189}
190
191/// Template-free fallback render: a `<section>` wrapping one `<div>` per
192/// field, class-hooked (`pb-group--<type>`, `pb-field--<name>`) so hosts
193/// can style without templates. Nested arrays (from any nested stream
194/// values) recurse through [`crate::block::render::prerender_stream`].
195fn generic_render(def: &DynBlockDef, value: &Value, ctx: &BlockRenderCtx<'_>) -> String {
196    let obj = value.as_object();
197    let mut out = format!(
198        "<section class=\"pb-group pb-group--{}\">",
199        tera::escape_html(def.type_name)
200    );
201    for field in &def.fields {
202        let BlockField::Widget { name, label, widget, options, .. } = field else {
203            continue;
204        };
205        let v = obj
206            .and_then(|o| o.get(name.as_str()))
207            .unwrap_or(&Value::Null);
208        let inner = if let Value::Array(_) = v {
209            if matches!(widget, crate::widget::WidgetKind::Checkboxes | crate::widget::WidgetKind::MultiSelect) {
210                crate::page_builder::values::public_value_html(&as_widget(name, label, *widget, options), v)
211            } else {
212                // Nested stream-shaped value — recurse (drift-safe).
213                crate::block::render::prerender_stream(v, ctx).ok()
214            }
215        } else {
216            // Same rules as a fixed field (#844): rich text sanitized,
217            // markdown rendered, choices by label; chooser ids are left
218            // out rather than printed.
219            crate::page_builder::values::public_value_html(&as_widget(name, label, *widget, options), v)
220        };
221        let Some(inner) = inner.filter(|h| !h.is_empty()) else {
222            continue;
223        };
224        out.push_str(&format!(
225            "<div class=\"pb-field pb-field--{}\">{inner}</div>",
226            tera::escape_html(name)
227        ));
228    }
229    out.push_str("</section>");
230    out
231}
232
233/// Wrapper so an `Arc<DynBlockDef>` can travel as a `Box<dyn Block>`
234/// alongside registry-owned blocks.
235struct ArcDynBlock(Arc<DynBlockDef>);
236
237impl Block for ArcDynBlock {
238    fn type_name(&self) -> &'static str {
239        self.0.type_name()
240    }
241    fn verbose_name(&self) -> &'static str {
242        self.0.verbose_name()
243    }
244    fn fields(&self) -> Vec<BlockField> {
245        self.0.fields()
246    }
247    fn icon(&self) -> Option<&'static str> {
248        self.0.icon()
249    }
250    fn group(&self) -> Option<&'static str> {
251        self.0.group()
252    }
253    fn description(&self) -> Option<&'static str> {
254        self.0.description()
255    }
256    fn label_format(&self) -> Option<&'static str> {
257        self.0.label_format()
258    }
259    fn version(&self) -> u32 {
260        self.0.version()
261    }
262    fn render(&self, value: &Value, ctx: &BlockRenderCtx<'_>) -> Result<String, BlockError> {
263        self.0.render(value, ctx)
264    }
265}
266
267/// Resolve a block type through the overlay first, then the inventory
268/// registry. THE lookup for every stream consumer that supports dyn
269/// blocks.
270#[must_use]
271pub fn resolve(set: Option<&DynBlockSet>, type_name: &str) -> Option<Box<dyn Block>> {
272    if let Some(def) = set.and_then(|s| s.get(type_name)) {
273        return Some(Box::new(ArcDynBlock(Arc::clone(def))));
274    }
275    crate::block::find_block(type_name)
276}
277
278#[cfg(test)]
279mod tests {
280    use super::*;
281    use crate::page_builder::schema::FieldNode;
282    use crate::widget::WidgetKind;
283
284    fn quote_group() -> GroupDef {
285        GroupDef {
286            key: "quote_pair".into(),
287            label: "Quote pair".into(),
288            icon: None,
289            description: None,
290            label_format: Some("{attribution}".into()),
291            children: vec![
292                Node::Field(FieldNode {
293                    key: "quote".into(),
294                    label: "Quote".into(),
295                    widget: WidgetKind::Textarea,
296                    ..Default::default()
297                }),
298                Node::Field(FieldNode {
299                    key: "attribution".into(),
300                    label: "By".into(),
301                    widget: WidgetKind::Text,
302                    ..Default::default()
303                }),
304            ],
305        }
306    }
307
308    #[test]
309    fn dyn_block_implements_block_shape() {
310        let def = DynBlockDef::from_group("quote_pair", &quote_group(), 7);
311        assert_eq!(def.type_name(), "quote_pair");
312        assert_eq!(def.verbose_name(), "Quote pair");
313        assert_eq!(def.version(), 7);
314        assert_eq!(def.label_format(), Some("{attribution}"));
315        assert_eq!(def.fields().len(), 2);
316    }
317
318    #[test]
319    fn intern_dedupes() {
320        let a = intern("same-string-x");
321        let b = intern("same-string-x");
322        assert!(
323            std::ptr::eq(a, b),
324            "second intern must return the cached ptr"
325        );
326    }
327
328    #[test]
329    fn generic_render_escapes_and_walks_fields() {
330        let def = DynBlockDef::from_group("quote_pair", &quote_group(), 1);
331        let tera = tera::Tera::default();
332        let ctx = BlockRenderCtx::new(&tera);
333        let html = def
334            .render(
335                &serde_json::json!({"quote": "a<b", "attribution": "Ada"}),
336                &ctx,
337            )
338            .expect("render");
339        assert!(html.contains("pb-group--quote_pair"), "{html}");
340        assert!(html.contains("a&lt;b"), "escaped: {html}");
341        assert!(html.contains("Ada"), "{html}");
342    }
343
344    #[test]
345    fn host_template_override_wins() {
346        let def = DynBlockDef::from_group("quote_pair", &quote_group(), 1);
347        let mut tera = tera::Tera::default();
348        tera.add_raw_template(
349            "blocks/quote_pair.html",
350            "<blockquote>{{ value.quote }}</blockquote>",
351        )
352        .unwrap();
353        let ctx = BlockRenderCtx::new(&tera);
354        let html = def
355            .render(&serde_json::json!({"quote": "hi"}), &ctx)
356            .expect("render");
357        assert_eq!(html, "<blockquote>hi</blockquote>");
358    }
359
360    #[test]
361    fn resolve_prefers_overlay_then_registry() {
362        let mut set: DynBlockSet = HashMap::new();
363        set.insert(
364            "quote_pair".to_owned(),
365            Arc::new(DynBlockDef::from_group("quote_pair", &quote_group(), 1)),
366        );
367        assert!(resolve(Some(&set), "quote_pair").is_some(), "overlay hit");
368        assert!(
369            resolve(Some(&set), "heading").is_some(),
370            "registry fallthrough"
371        );
372        assert!(
373            resolve(None, "quote_pair").is_none(),
374            "no overlay, not registered"
375        );
376    }
377}