Skip to main content

rustango_cms/block/
builtin.rs

1//! Built-in blocks shipped with rcms. Each one is a single Rust
2//! struct plus a Tera template at `blocks/<type_name>.html` (in
3//! [`crate::admin::register_templates`]). Host crates register
4//! additional blocks via [`crate::register_block!`].
5//!
6//! These ship with sensible defaults and a minimal HTML template so
7//! the editor + render path produce a working page on day one. Hosts
8//! can override the template by registering a same-named template
9//! before the bundled load — Tera resolves the most-recently-added
10//! template, which is the standard precedence rule.
11
12use crate::block::BlockFieldMeta;
13use crate::widget::WidgetKind;
14use crate::{register_block, Block, BlockField};
15
16/// `heading` — a heading with a level choice. Two fields:
17/// `text` (the heading body) and `level` (`2`..`4`, defaulting to
18/// H2). Template emits `<h{level}>{text}</h{level}>`.
19#[derive(Default)]
20pub struct HeadingBlock;
21
22impl Block for HeadingBlock {
23    fn type_name(&self) -> &'static str {
24        "heading"
25    }
26    fn verbose_name(&self) -> &'static str {
27        "Heading"
28    }
29    fn icon(&self) -> Option<&'static str> {
30        Some("title")
31    }
32    fn label_format(&self) -> Option<&'static str> {
33        Some("{text}")
34    }
35    fn preview_value(&self) -> Option<serde_json::Value> {
36        Some(serde_json::json!({ "text": "Example heading", "level": "2" }))
37    }
38    // Reads as straight English now: "text is a required char field,
39    // level is a choice of H2/H3/H4". Compare with the previous
40    // ~24-line match-arm form — same shape, ~75% fewer lines.
41    fn fields(&self) -> Vec<BlockField> {
42        vec![
43            BlockField::char("text", "Text").required(),
44            BlockField::choice("level", "Level", [("2", "H2"), ("3", "H3"), ("4", "H4")]),
45        ]
46    }
47}
48
49/// `paragraph` — One markdown field
50/// rendered through the rcms safe-markdown pipeline on the public
51/// side.
52#[derive(Default)]
53pub struct ParagraphBlock;
54
55impl Block for ParagraphBlock {
56    fn type_name(&self) -> &'static str {
57        "paragraph"
58    }
59    fn verbose_name(&self) -> &'static str {
60        "Paragraph"
61    }
62    fn icon(&self) -> Option<&'static str> {
63        Some("notes")
64    }
65    fn fields(&self) -> Vec<BlockField> {
66        vec![BlockField::Widget {
67            name: "body".to_owned(),
68            label: "Body".to_owned(),
69            widget: WidgetKind::Markdown,
70            options: Vec::new(),
71            help: Some("GFM markdown.".to_owned()),
72            required: true,
73            meta: BlockFieldMeta::default(),
74        }]
75    }
76}
77
78/// `image` — Picks a `cms_media` row
79/// + optional alt text + optional caption. Template emits a `<figure>`
80/// with the image URL resolved server-side.
81#[derive(Default)]
82pub struct ImageBlock;
83
84impl Block for ImageBlock {
85    fn type_name(&self) -> &'static str {
86        "image"
87    }
88    fn verbose_name(&self) -> &'static str {
89        "Image"
90    }
91    fn icon(&self) -> Option<&'static str> {
92        Some("image")
93    }
94    fn fields(&self) -> Vec<BlockField> {
95        vec![
96            BlockField::Widget {
97                name: "media_id".to_owned(),
98                label: "Image".to_owned(),
99                widget: WidgetKind::MediaPicker,
100                options: Vec::new(),
101                help: None,
102                required: true,
103                meta: BlockFieldMeta::default(),
104            },
105            BlockField::Widget {
106                name: "alt".to_owned(),
107                label: "Alt text".to_owned(),
108                widget: WidgetKind::Text,
109                options: Vec::new(),
110                help: Some("Empty if decorative.".to_owned()),
111                required: false,
112                meta: BlockFieldMeta::default(),
113            },
114            BlockField::Widget {
115                name: "caption".to_owned(),
116                label: "Caption".to_owned(),
117                widget: WidgetKind::Text,
118                options: Vec::new(),
119                help: None,
120                required: false,
121                meta: BlockFieldMeta::default(),
122            },
123        ]
124    }
125}
126
127/// `quote` — Textarea body + optional
128/// attribution.
129#[derive(Default)]
130pub struct QuoteBlock;
131
132impl Block for QuoteBlock {
133    fn type_name(&self) -> &'static str {
134        "quote"
135    }
136    fn verbose_name(&self) -> &'static str {
137        "Quote"
138    }
139    fn icon(&self) -> Option<&'static str> {
140        Some("format_quote")
141    }
142    fn label_format(&self) -> Option<&'static str> {
143        Some("“{text}”")
144    }
145    fn preview_value(&self) -> Option<serde_json::Value> {
146        Some(serde_json::json!({
147            "text": "The best way to predict the future is to invent it.",
148            "attribution": "Alan Kay"
149        }))
150    }
151    fn fields(&self) -> Vec<BlockField> {
152        vec![
153            BlockField::Widget {
154                name: "text".to_owned(),
155                label: "Quote".to_owned(),
156                widget: WidgetKind::Textarea,
157                options: Vec::new(),
158                help: None,
159                required: true,
160                meta: BlockFieldMeta::default(),
161            },
162            BlockField::Widget {
163                name: "attribution".to_owned(),
164                label: "Attribution".to_owned(),
165                widget: WidgetKind::Text,
166                options: Vec::new(),
167                help: None,
168                required: false,
169                meta: BlockFieldMeta::default(),
170            },
171        ]
172    }
173}
174
175/// `embed` — A single URL; the public
176/// template renders a responsive embed. [`Self::extra_context`] runs
177/// the URL through [`crate::embed::resolve`] so a YouTube
178/// *watch* or Vimeo *page* URL becomes the provider's embeddable
179/// `src` with the right aspect ratio; unrecognised URLs link out
180/// rather than iframing an arbitrary site.
181#[derive(Default)]
182pub struct EmbedBlock;
183
184impl Block for EmbedBlock {
185    fn type_name(&self) -> &'static str {
186        "embed"
187    }
188    fn verbose_name(&self) -> &'static str {
189        "Embed"
190    }
191    fn icon(&self) -> Option<&'static str> {
192        Some("smart_display")
193    }
194    fn fields(&self) -> Vec<BlockField> {
195        vec![BlockField::Widget {
196            name: "url".to_owned(),
197            label: "URL".to_owned(),
198            widget: WidgetKind::Url,
199            options: Vec::new(),
200            help: Some("YouTube or Vimeo URL (others link out).".to_owned()),
201            required: true,
202            meta: BlockFieldMeta::default(),
203        }]
204    }
205
206    fn extra_context(
207        &self,
208        value: &serde_json::Value,
209        _ctx: &crate::block::BlockRenderCtx<'_>,
210    ) -> serde_json::Map<String, serde_json::Value> {
211        let url = value
212            .get("url")
213            .and_then(serde_json::Value::as_str)
214            .unwrap_or("")
215            .trim();
216        // Always insert the three keys (empty when unrecognised) so the
217        // template can branch with a plain `{% if embed_src %}` without
218        // tripping Tera's undefined-variable error.
219        let (src, provider, aspect) = match crate::embed::resolve(url) {
220            Some(t) => (
221                t.src,
222                t.provider.name().to_owned(),
223                t.aspect_ratio.to_owned(),
224            ),
225            None => (String::new(), String::new(), String::new()),
226        };
227        let mut m = serde_json::Map::new();
228        m.insert("embed_src".to_owned(), serde_json::Value::String(src));
229        m.insert("provider".to_owned(), serde_json::Value::String(provider));
230        m.insert("aspect_ratio".to_owned(), serde_json::Value::String(aspect));
231        m.insert("safe_href".to_owned(), safe_href_value(url));
232        m
233    }
234}
235
236/// An author-typed link target, or `None` when it would run script.
237///
238/// The url and embed inputs only validate in the browser, so a
239/// `javascript:` (or `vbscript:` / `data:`) value reaches the rendered
240/// `href` otherwise. Relative targets and the http(s), mailto and
241/// tel schemes pass. The scheme is read the way a browser reads it, with
242/// tabs, newlines and other control characters removed, so `java\tscript:`
243/// is caught too.
244#[must_use]
245pub fn safe_href(raw: &str) -> Option<&str> {
246    let raw = raw.trim();
247    let squashed: String = raw.chars().filter(|c| !c.is_ascii_control() && *c != ' ').collect();
248    let scheme = match squashed.find([':', '/', '?', '#']) {
249        Some(i) if squashed[i..].starts_with(':') => squashed[..i].to_ascii_lowercase(),
250        _ => return Some(raw),
251    };
252    matches!(scheme.as_str(), "http" | "https" | "mailto" | "tel").then_some(raw)
253}
254
255fn safe_href_value(raw: &str) -> serde_json::Value {
256    serde_json::Value::String(safe_href(raw).unwrap_or_default().to_owned())
257}
258
259/// Curated languages for [`CodeBlock`]'s dropdown. Values are the
260/// highlighter token emitted in the `language-…` class.
261const CODE_LANGUAGES: &[(&str, &str)] = &[
262    ("bash", "Bash / shell"),
263    ("c", "C"),
264    ("cpp", "C++"),
265    ("csharp", "C#"),
266    ("css", "CSS"),
267    ("diff", "Diff"),
268    ("dockerfile", "Dockerfile"),
269    ("go", "Go"),
270    ("html", "HTML"),
271    ("java", "Java"),
272    ("javascript", "JavaScript"),
273    ("json", "JSON"),
274    ("kotlin", "Kotlin"),
275    ("markdown", "Markdown"),
276    ("php", "PHP"),
277    ("python", "Python"),
278    ("ruby", "Ruby"),
279    ("rust", "Rust"),
280    ("scss", "SCSS"),
281    ("sql", "SQL"),
282    ("swift", "Swift"),
283    ("toml", "TOML"),
284    ("typescript", "TypeScript"),
285    ("xml", "XML"),
286    ("yaml", "YAML"),
287];
288
289/// `code` — a fenced code block with a language hint. Renders
290/// the standard `<pre><code class="language-…">` markup that client
291/// highlighters (Prism / highlight.js / Shiki) pick up automatically.
292/// The body is HTML-escaped by Tera, so it displays verbatim and can't
293/// inject markup. Server-side highlighting (syntect) would add a heavy
294/// dependency and is better as an opt-in follow-up — this markup is
295/// highlighter-agnostic.
296#[derive(Default)]
297pub struct CodeBlock;
298
299impl Block for CodeBlock {
300    fn type_name(&self) -> &'static str {
301        "code"
302    }
303    fn verbose_name(&self) -> &'static str {
304        "Code"
305    }
306    fn icon(&self) -> Option<&'static str> {
307        Some("code")
308    }
309    fn fields(&self) -> Vec<BlockField> {
310        vec![
311            BlockField::choice("language", "Language", CODE_LANGUAGES.iter().copied()),
312            BlockField::text("code", "Code").required(),
313        ]
314    }
315    fn preview_value(&self) -> Option<serde_json::Value> {
316        Some(serde_json::json!({
317            "language": "rust",
318            "code": "fn main() {\n    println!(\"hello\");\n}",
319        }))
320    }
321}
322
323/// `text` — Multi-line plain text rendered
324/// inside `<p>` with newlines preserved.
325#[derive(Default)]
326pub struct TextBlock;
327
328impl Block for TextBlock {
329    fn type_name(&self) -> &'static str {
330        "text"
331    }
332    fn verbose_name(&self) -> &'static str {
333        "Text"
334    }
335    fn icon(&self) -> Option<&'static str> {
336        Some("text_fields")
337    }
338    fn fields(&self) -> Vec<BlockField> {
339        vec![BlockField::Widget {
340            name: "body".to_owned(),
341            label: "Body".to_owned(),
342            widget: WidgetKind::Textarea,
343            options: Vec::new(),
344            help: None,
345            required: true,
346            meta: BlockFieldMeta::default(),
347        }]
348    }
349}
350
351/// `boolean` — Single checkbox; the template
352/// renders nothing by default (host overrides decide what "true"
353/// means in context — show a banner, flip a class, …).
354#[derive(Default)]
355pub struct BooleanBlock;
356
357impl Block for BooleanBlock {
358    fn type_name(&self) -> &'static str {
359        "boolean"
360    }
361    fn verbose_name(&self) -> &'static str {
362        "Boolean (checkbox)"
363    }
364    fn icon(&self) -> Option<&'static str> {
365        Some("check_box")
366    }
367    fn fields(&self) -> Vec<BlockField> {
368        vec![BlockField::Widget {
369            name: "value".to_owned(),
370            label: "Checked".to_owned(),
371            widget: WidgetKind::Boolean,
372            options: Vec::new(),
373            help: None,
374            required: false,
375            meta: BlockFieldMeta::default(),
376        }]
377    }
378}
379
380/// `date` — ISO-8601 date string (`YYYY-MM-DD`).
381#[derive(Default)]
382pub struct DateBlock;
383
384impl Block for DateBlock {
385    fn type_name(&self) -> &'static str {
386        "date"
387    }
388    fn verbose_name(&self) -> &'static str {
389        "Date"
390    }
391    fn icon(&self) -> Option<&'static str> {
392        Some("calendar_today")
393    }
394    fn fields(&self) -> Vec<BlockField> {
395        vec![BlockField::Widget {
396            name: "value".to_owned(),
397            label: "Date".to_owned(),
398            widget: WidgetKind::Date,
399            options: Vec::new(),
400            help: None,
401            required: true,
402            meta: BlockFieldMeta::default(),
403        }]
404    }
405}
406
407/// `datetime` — ISO-8601 datetime string.
408#[derive(Default)]
409pub struct DateTimeBlock;
410
411impl Block for DateTimeBlock {
412    fn type_name(&self) -> &'static str {
413        "datetime"
414    }
415    fn verbose_name(&self) -> &'static str {
416        "Date & time"
417    }
418    fn icon(&self) -> Option<&'static str> {
419        Some("event")
420    }
421    fn fields(&self) -> Vec<BlockField> {
422        vec![BlockField::Widget {
423            name: "value".to_owned(),
424            label: "When".to_owned(),
425            widget: WidgetKind::Datetime,
426            options: Vec::new(),
427            help: None,
428            required: true,
429            meta: BlockFieldMeta::default(),
430        }]
431    }
432}
433
434/// `email` — Browser-validates the shape via
435/// `<input type="email">`; the template renders a `mailto:` link.
436#[derive(Default)]
437pub struct EmailBlock;
438
439impl Block for EmailBlock {
440    fn type_name(&self) -> &'static str {
441        "email"
442    }
443    fn verbose_name(&self) -> &'static str {
444        "Email"
445    }
446    fn icon(&self) -> Option<&'static str> {
447        Some("mail")
448    }
449    fn fields(&self) -> Vec<BlockField> {
450        vec![
451            BlockField::Widget {
452                name: "value".to_owned(),
453                label: "Email address".to_owned(),
454                widget: WidgetKind::Email,
455                options: Vec::new(),
456                help: None,
457                required: true,
458                meta: BlockFieldMeta::default(),
459            },
460            BlockField::Widget {
461                name: "label".to_owned(),
462                label: "Display label".to_owned(),
463                widget: WidgetKind::Text,
464                options: Vec::new(),
465                help: Some("Defaults to the email address itself.".to_owned()),
466                required: false,
467                meta: BlockFieldMeta::default(),
468            },
469        ]
470    }
471}
472
473/// `url` — Browser-validates via
474/// `<input type="url">`; the template renders an anchor.
475#[derive(Default)]
476pub struct UrlBlock;
477
478impl Block for UrlBlock {
479    fn type_name(&self) -> &'static str {
480        "url"
481    }
482    fn verbose_name(&self) -> &'static str {
483        "URL"
484    }
485    fn icon(&self) -> Option<&'static str> {
486        Some("link")
487    }
488    fn fields(&self) -> Vec<BlockField> {
489        vec![
490            BlockField::Widget {
491                name: "value".to_owned(),
492                label: "URL".to_owned(),
493                widget: WidgetKind::Url,
494                options: Vec::new(),
495                help: None,
496                required: true,
497                meta: BlockFieldMeta::default(),
498            },
499            BlockField::Widget {
500                name: "label".to_owned(),
501                label: "Display label".to_owned(),
502                widget: WidgetKind::Text,
503                options: Vec::new(),
504                help: Some("Defaults to the URL itself.".to_owned()),
505                required: false,
506                meta: BlockFieldMeta::default(),
507            },
508        ]
509    }
510
511    fn extra_context(
512        &self,
513        value: &serde_json::Value,
514        _ctx: &crate::block::BlockRenderCtx<'_>,
515    ) -> serde_json::Map<String, serde_json::Value> {
516        let raw = value.get("value").and_then(serde_json::Value::as_str).unwrap_or("");
517        let mut m = serde_json::Map::new();
518        m.insert("safe_href".to_owned(), safe_href_value(raw));
519        m
520    }
521}
522
523/// `integer` — Numeric input; the template
524/// renders the value as-is. Editors needing a unit / formatting
525/// override the template.
526#[derive(Default)]
527pub struct IntegerBlock;
528
529impl Block for IntegerBlock {
530    fn type_name(&self) -> &'static str {
531        "integer"
532    }
533    fn verbose_name(&self) -> &'static str {
534        "Integer"
535    }
536    fn icon(&self) -> Option<&'static str> {
537        Some("123")
538    }
539    fn fields(&self) -> Vec<BlockField> {
540        vec![BlockField::Widget {
541            name: "value".to_owned(),
542            label: "Value".to_owned(),
543            widget: WidgetKind::Number,
544            options: Vec::new(),
545            help: None,
546            required: true,
547            meta: BlockFieldMeta::default(),
548        }]
549    }
550}
551
552/// `choice` — Editor picks one entry from a
553/// host-supplied list of `(value, label)` pairs. Hosts override
554/// [`Block::fields`] by subclassing to set their own option list
555/// (the registered default lands as an empty select — actionable
556/// only when a host extends).
557///
558/// Authors who want richer choices should register a per-site
559/// `ChoiceBlock` variant via `register_block!` with their own list.
560#[derive(Default)]
561pub struct ChoiceBlock;
562
563impl Block for ChoiceBlock {
564    fn type_name(&self) -> &'static str {
565        "choice"
566    }
567    fn verbose_name(&self) -> &'static str {
568        "Choice"
569    }
570    fn icon(&self) -> Option<&'static str> {
571        Some("list_alt")
572    }
573    fn fields(&self) -> Vec<BlockField> {
574        vec![BlockField::Widget {
575            name: "value".to_owned(),
576            label: "Choice".to_owned(),
577            widget: WidgetKind::Select,
578            // Empty by default — hosts override the template or
579            // register a subclassed block with their own options.
580            options: Vec::new(),
581            help: Some(
582                "Pick a value from the host-configured list. Edit the block to extend choices."
583                    .to_owned(),
584            ),
585            required: true,
586            meta: BlockFieldMeta::default(),
587        }]
588    }
589}
590
591/// `table` — Editor enters TSV (one row per
592/// line, tab-separated cells); the public template renders a
593/// `<table>` with the first row as `<thead>`. Cells preserve as
594/// plain text. Pasting straight from a spreadsheet works because
595/// Excel / Google Sheets / Numbers all serialise selected ranges
596/// as TSV on the clipboard.
597///
598/// TypedTableBlock (schema-driven columns) lives as a separate
599/// future block — the data shape differs enough to warrant its
600/// own type.
601#[derive(Default)]
602pub struct TableBlock;
603
604impl Block for TableBlock {
605    fn type_name(&self) -> &'static str {
606        "table"
607    }
608    fn verbose_name(&self) -> &'static str {
609        "Table"
610    }
611    fn icon(&self) -> Option<&'static str> {
612        Some("table")
613    }
614    fn fields(&self) -> Vec<BlockField> {
615        vec![
616            BlockField::Widget {
617                name: "tsv".to_owned(),
618                label: "Rows".to_owned(),
619                widget: WidgetKind::Textarea,
620                options: Vec::new(),
621                help: Some(
622                    "One row per line, columns separated by tabs. The first row renders as <thead>. Paste from a spreadsheet to fill — Excel / Sheets / Numbers all copy as TSV."
623                        .to_owned(),
624                ),
625                required: true,
626                meta: BlockFieldMeta::default(),
627            },
628            BlockField::Widget {
629                name: "caption".to_owned(),
630                label: "Caption".to_owned(),
631                widget: WidgetKind::Text,
632                options: Vec::new(),
633                help: None,
634                required: false,
635                meta: BlockFieldMeta::default(),
636            },
637        ]
638    }
639}
640
641/// `float` — Free-form floating-point input.
642/// Distinct from `IntegerBlock` (which uses `WidgetKind::Number` with
643/// `step="1"`) — this one accepts decimals.
644#[derive(Default)]
645pub struct FloatBlock;
646
647impl Block for FloatBlock {
648    fn type_name(&self) -> &'static str {
649        "float"
650    }
651    fn verbose_name(&self) -> &'static str {
652        "Float"
653    }
654    fn icon(&self) -> Option<&'static str> {
655        Some("decimal_increase")
656    }
657    fn fields(&self) -> Vec<BlockField> {
658        vec![BlockField::Widget {
659            name: "value".to_owned(),
660            label: "Value".to_owned(),
661            widget: WidgetKind::Float,
662            options: Vec::new(),
663            help: None,
664            required: true,
665            meta: BlockFieldMeta::default(),
666        }]
667    }
668}
669
670/// `time` — ISO `HH:MM[:SS]` string.
671#[derive(Default)]
672pub struct TimeBlock;
673
674impl Block for TimeBlock {
675    fn type_name(&self) -> &'static str {
676        "time"
677    }
678    fn verbose_name(&self) -> &'static str {
679        "Time"
680    }
681    fn icon(&self) -> Option<&'static str> {
682        Some("schedule")
683    }
684    fn fields(&self) -> Vec<BlockField> {
685        vec![BlockField::Widget {
686            name: "value".to_owned(),
687            label: "Time".to_owned(),
688            widget: WidgetKind::Time,
689            options: Vec::new(),
690            help: None,
691            required: true,
692            meta: BlockFieldMeta::default(),
693        }]
694    }
695}
696
697/// `multiple_choice` — Distinct from
698/// `ChoiceBlock` (single-pick `<select>`) — this one renders stacked
699/// checkboxes and stores a JSON-array string. Hosts register a
700/// subclassed variant with their own option list (default ships with
701/// no options, like `ChoiceBlock`).
702#[derive(Default)]
703pub struct MultipleChoiceBlock;
704
705impl Block for MultipleChoiceBlock {
706    fn type_name(&self) -> &'static str {
707        "multiple_choice"
708    }
709    fn verbose_name(&self) -> &'static str {
710        "Multiple choice"
711    }
712    fn icon(&self) -> Option<&'static str> {
713        Some("checklist")
714    }
715    fn fields(&self) -> Vec<BlockField> {
716        vec![BlockField::Widget {
717            name: "values".to_owned(),
718            label: "Choices".to_owned(),
719            widget: WidgetKind::Checkboxes,
720            options: Vec::new(),
721            help: Some(
722                "Pick zero or more values from the host-configured list. Stored as a JSON array."
723                    .to_owned(),
724            ),
725            required: false,
726            meta: BlockFieldMeta::default(),
727        }]
728    }
729    fn render(
730        &self,
731        value: &serde_json::Value,
732        ctx: &crate::block::BlockRenderCtx<'_>,
733    ) -> Result<String, crate::block::BlockError> {
734        // Pre-parse the JSON-array string stored by the Checkboxes
735        // widget into a real array so the template can iterate
736        // without a custom `json_decode` filter. Falls back to an
737        // empty array on bad input — better than failing render.
738        let mut prepared = value.as_object().cloned().unwrap_or_default();
739        let parsed: Vec<serde_json::Value> = prepared
740            .get("values")
741            .and_then(serde_json::Value::as_str)
742            .and_then(|s| serde_json::from_str(s).ok())
743            .unwrap_or_default();
744        prepared.insert("values".to_owned(), serde_json::Value::Array(parsed));
745        crate::block::render::default_render(self, &serde_json::Value::Object(prepared), ctx)
746    }
747}
748
749/// `static` — Marker block with no fields;
750/// the public template emits whatever static HTML the host wants
751/// (divider, call-out, branded heading rule). Inserting one in a
752/// StreamField is the editor's signal "render the host's static
753/// content here".
754#[derive(Default)]
755pub struct StaticBlock;
756
757impl Block for StaticBlock {
758    fn type_name(&self) -> &'static str {
759        "static"
760    }
761    fn verbose_name(&self) -> &'static str {
762        "Static block"
763    }
764    fn icon(&self) -> Option<&'static str> {
765        Some("horizontal_rule")
766    }
767    fn fields(&self) -> Vec<BlockField> {
768        // Intentionally empty — the host template controls the output.
769        Vec::new()
770    }
771}
772
773/// `raw_html` — Editor types HTML; the
774/// public template sanitises through the same ammonia pipeline as
775/// the Markdown widget (`crate::markdown::render`'s post-pass) so
776/// `<script>` / `<iframe>` / `on*` handlers are stripped.
777///
778/// Distinct from `ParagraphBlock` (markdown source → rendered HTML)
779/// — this one stores HTML directly. Use when content authors already
780/// have hand-written HTML they want to drop in.
781#[derive(Default)]
782pub struct RawHtmlBlock;
783
784impl Block for RawHtmlBlock {
785    fn type_name(&self) -> &'static str {
786        "raw_html"
787    }
788    fn verbose_name(&self) -> &'static str {
789        "Raw HTML"
790    }
791    fn icon(&self) -> Option<&'static str> {
792        Some("code")
793    }
794    fn fields(&self) -> Vec<BlockField> {
795        vec![BlockField::Widget {
796            name: "html".to_owned(),
797            label: "HTML".to_owned(),
798            widget: WidgetKind::Textarea,
799            options: Vec::new(),
800            help: Some(
801                "Raw HTML. The public template sanitises through ammonia before render — script / iframe / on* attrs are stripped."
802                    .to_owned(),
803            ),
804            required: true,
805            meta: BlockFieldMeta::default(),
806        }]
807    }
808    fn render(
809        &self,
810        value: &serde_json::Value,
811        ctx: &crate::block::BlockRenderCtx<'_>,
812    ) -> Result<String, crate::block::BlockError> {
813        // Pre-sanitise the stored HTML through the same ammonia
814        // pipeline `markdown::render` uses for its post-pass, then
815        // hand the cleaned string to the template marked `| safe`.
816        // Editors typing `<script>` get a no-op render rather than
817        // an XSS vector.
818        let mut prepared = value.as_object().cloned().unwrap_or_default();
819        let cleaned = prepared
820            .get("html")
821            .and_then(serde_json::Value::as_str)
822            .map(ammonia::clean)
823            .unwrap_or_default();
824        prepared.insert("html".to_owned(), serde_json::Value::String(cleaned));
825        crate::block::render::default_render(self, &serde_json::Value::Object(prepared), ctx)
826    }
827}
828
829/// `page_chooser` — Picks a single
830/// `cms_page` row via the modal `PageChooser` widget; stores the page
831/// id as a stringified integer.
832///
833/// The public template receives `value.page_id` (string) — host
834/// templates resolve the page via Tera helpers (`url_for_page`) or
835/// override the template to render an internal link.
836#[derive(Default)]
837pub struct PageChooserBlock;
838
839impl Block for PageChooserBlock {
840    fn type_name(&self) -> &'static str {
841        "page_chooser"
842    }
843    fn verbose_name(&self) -> &'static str {
844        "Page link"
845    }
846    fn icon(&self) -> Option<&'static str> {
847        Some("article")
848    }
849    fn description(&self) -> Option<&'static str> {
850        Some("Link to another page in this site.")
851    }
852    fn fields(&self) -> Vec<BlockField> {
853        vec![
854            BlockField::Widget {
855                name: "page_id".to_owned(),
856                label: "Page".to_owned(),
857                widget: WidgetKind::PageChooser,
858                options: Vec::new(),
859                help: None,
860                required: true,
861                meta: BlockFieldMeta::default(),
862            },
863            BlockField::Widget {
864                name: "label".to_owned(),
865                label: "Display label".to_owned(),
866                widget: WidgetKind::Text,
867                options: Vec::new(),
868                help: Some("Optional override — defaults to the chosen page's title.".to_owned()),
869                required: false,
870                meta: BlockFieldMeta::default(),
871            },
872        ]
873    }
874}
875
876/// `snippet_chooser` — Picks a
877/// `cms_snippet` row via the modal `SnippetChooser` widget. The
878/// stored value is the snippet id as a stringified integer.
879///
880/// Hosts that want to narrow the picker to one snippet `type_name`
881/// register a subclassed variant + set `Widget::custom_name` on the
882/// chooser field at construction (admin reads it via
883/// `data-chooser-filter`). The default ships unfiltered so editors
884/// can pick any snippet.
885#[derive(Default)]
886pub struct SnippetChooserBlock;
887
888impl Block for SnippetChooserBlock {
889    fn type_name(&self) -> &'static str {
890        "snippet_chooser"
891    }
892    fn verbose_name(&self) -> &'static str {
893        "Snippet"
894    }
895    fn icon(&self) -> Option<&'static str> {
896        Some("library_books")
897    }
898    fn description(&self) -> Option<&'static str> {
899        Some("Pick a reusable snippet from the library.")
900    }
901    fn fields(&self) -> Vec<BlockField> {
902        vec![BlockField::Widget {
903            name: "snippet_id".to_owned(),
904            label: "Snippet".to_owned(),
905            widget: WidgetKind::SnippetChooser,
906            options: Vec::new(),
907            help: None,
908            required: true,
909            meta: BlockFieldMeta::default(),
910        }]
911    }
912}
913
914/// `document_chooser` — Picks a
915/// non-image `cms_media` row (e.g. PDF, archive) via the modal
916/// `DocumentChooser` widget. Stored value is the media id as a
917/// stringified integer.
918#[derive(Default)]
919pub struct DocumentChooserBlock;
920
921impl Block for DocumentChooserBlock {
922    fn type_name(&self) -> &'static str {
923        "document_chooser"
924    }
925    fn verbose_name(&self) -> &'static str {
926        "Document link"
927    }
928    fn icon(&self) -> Option<&'static str> {
929        Some("description")
930    }
931    fn description(&self) -> Option<&'static str> {
932        Some("Link to a PDF or other non-image document in the media library.")
933    }
934    fn fields(&self) -> Vec<BlockField> {
935        vec![
936            BlockField::Widget {
937                name: "document_id".to_owned(),
938                label: "Document".to_owned(),
939                widget: WidgetKind::DocumentChooser,
940                options: Vec::new(),
941                help: None,
942                required: true,
943                meta: BlockFieldMeta::default(),
944            },
945            BlockField::Widget {
946                name: "label".to_owned(),
947                label: "Display label".to_owned(),
948                widget: WidgetKind::Text,
949                options: Vec::new(),
950                help: Some("Optional — defaults to the document's title.".to_owned()),
951                required: false,
952                meta: BlockFieldMeta::default(),
953            },
954        ]
955    }
956}
957
958register_block!(HeadingBlock);
959register_block!(ParagraphBlock);
960register_block!(ImageBlock);
961register_block!(QuoteBlock);
962register_block!(EmbedBlock);
963register_block!(CodeBlock);
964register_block!(TextBlock);
965register_block!(BooleanBlock);
966register_block!(DateBlock);
967register_block!(DateTimeBlock);
968register_block!(EmailBlock);
969register_block!(UrlBlock);
970register_block!(IntegerBlock);
971register_block!(ChoiceBlock);
972register_block!(TableBlock);
973/// `typed_table_row` — one row inside the default TypedTableBlock.
974/// Three columns: `label` (text), `value` (number), `notes` (text).
975/// This serves as a working baseline; hosts that need a different
976/// column schema register their own row block + their own
977/// `TypedTable`-style wrapper.
978///
979/// Hosts subclass by registering a new row block with the columns
980/// they want, then registering a wrapper block whose `fields()`
981/// returns `BlockField::repeat("rows", "Rows", "<their_row_type>")`.
982#[derive(Default)]
983pub struct TypedTableRowBlock;
984
985impl Block for TypedTableRowBlock {
986    fn type_name(&self) -> &'static str {
987        "typed_table_row"
988    }
989    fn verbose_name(&self) -> &'static str {
990        "Table row"
991    }
992    fn icon(&self) -> Option<&'static str> {
993        Some("table_rows")
994    }
995    fn description(&self) -> Option<&'static str> {
996        Some("One row in a typed table. Subclass to define your own columns.")
997    }
998    fn fields(&self) -> Vec<BlockField> {
999        vec![
1000            BlockField::Widget {
1001                name: "label".to_owned(),
1002                label: "Label".to_owned(),
1003                widget: WidgetKind::Text,
1004                options: Vec::new(),
1005                help: None,
1006                required: true,
1007                meta: BlockFieldMeta::default(),
1008            },
1009            BlockField::Widget {
1010                name: "value".to_owned(),
1011                label: "Value".to_owned(),
1012                widget: WidgetKind::Number,
1013                options: Vec::new(),
1014                help: None,
1015                required: false,
1016                meta: BlockFieldMeta::default(),
1017            },
1018            BlockField::Widget {
1019                name: "notes".to_owned(),
1020                label: "Notes".to_owned(),
1021                widget: WidgetKind::Text,
1022                options: Vec::new(),
1023                help: None,
1024                required: false,
1025                meta: BlockFieldMeta::default(),
1026            },
1027        ]
1028    }
1029}
1030
1031/// `typed_table` — Schema-driven typed
1032/// grid where each row's cells are individually-typed widgets (unlike
1033/// `TableBlock` which is TSV-only).
1034///
1035/// Wire shape:
1036/// ```text
1037/// { "caption": "...", "rows": [
1038///     { "type": "typed_table_row", "id": "uuid", "value": { "label": ..., "value": ..., "notes": ... }}
1039/// ]}
1040/// ```
1041///
1042/// Editor UX: today renders as a stacked list of typed input rows
1043/// (one form-row per data-row) — a real spreadsheet-style grid is a
1044/// future enhancement. The `Repeat` BlockField underneath gives
1045/// add / remove / move-up / move-down out of the box from the
1046/// existing stream editor JS.
1047///
1048/// Hosts subclass by registering their own row block + their own
1049/// wrapper block; the default ships with the three-column row above
1050/// as a working baseline.
1051#[derive(Default)]
1052pub struct TypedTableBlock;
1053
1054impl Block for TypedTableBlock {
1055    fn type_name(&self) -> &'static str {
1056        "typed_table"
1057    }
1058    fn verbose_name(&self) -> &'static str {
1059        "Typed table"
1060    }
1061    fn icon(&self) -> Option<&'static str> {
1062        Some("grid_on")
1063    }
1064    fn description(&self) -> Option<&'static str> {
1065        Some("Typed grid — each column is a properly-typed widget. Subclass to define your own columns.")
1066    }
1067    fn fields(&self) -> Vec<BlockField> {
1068        vec![
1069            BlockField::Widget {
1070                name: "caption".to_owned(),
1071                label: "Caption".to_owned(),
1072                widget: WidgetKind::Text,
1073                options: Vec::new(),
1074                help: None,
1075                required: false,
1076                meta: BlockFieldMeta::default(),
1077            },
1078            BlockField::Repeat {
1079                name: "rows".to_owned(),
1080                label: "Rows".to_owned(),
1081                item_type: "typed_table_row".to_owned(),
1082                min: None,
1083                max: None,
1084            },
1085        ]
1086    }
1087}
1088
1089/// `rich_text` — Editor surface for
1090/// hosts wiring a WYSIWYG (EasyMDE / TipTap / Draftail) via the
1091/// `WidgetKind::RichText` widget's `data-widget-mode="richtext"`
1092/// hook. Without a host enhancer the textarea ships with the
1093/// existing markdown toolbar — same editor as ParagraphBlock
1094/// but stores HTML directly.
1095///
1096/// Distinct from:
1097/// - `ParagraphBlock` (markdown source → rendered via the markdown
1098///   pipeline)
1099/// - `RawHtmlBlock` (plain `<textarea>` for HTML, no WYSIWYG hook)
1100///
1101/// Render path: stored HTML through ammonia sanitisation — script /
1102/// iframe / on* attrs stripped — then emitted with `| safe`.
1103#[derive(Default)]
1104pub struct RichTextBlock;
1105
1106impl Block for RichTextBlock {
1107    fn type_name(&self) -> &'static str {
1108        "rich_text"
1109    }
1110    fn verbose_name(&self) -> &'static str {
1111        "Rich text"
1112    }
1113    fn icon(&self) -> Option<&'static str> {
1114        Some("article")
1115    }
1116    fn description(&self) -> Option<&'static str> {
1117        Some("Formatted text — hosts wire a WYSIWYG via the richtext widget hook.")
1118    }
1119    fn fields(&self) -> Vec<BlockField> {
1120        vec![BlockField::Widget {
1121            name: "body".to_owned(),
1122            label: "Body".to_owned(),
1123            widget: WidgetKind::RichText,
1124            options: Vec::new(),
1125            help: Some(
1126                "Hosts swap in EasyMDE / TipTap / Draftail via the richtext widget hook. Without one, the editor falls back to the markdown toolbar."
1127                    .to_owned(),
1128            ),
1129            required: true,
1130            meta: BlockFieldMeta::default(),
1131        }]
1132    }
1133    fn render(
1134        &self,
1135        value: &serde_json::Value,
1136        ctx: &crate::block::BlockRenderCtx<'_>,
1137    ) -> Result<String, crate::block::BlockError> {
1138        // Sanitise with the rich-text policy, which keeps the editor's
1139        // move-safe `<a linktype="page|media" id="N">` anchors (default
1140        // ammonia strips `linktype`/`id`, which left every internal link
1141        // in a block without a target — #682). The page render resolves
1142        // them afterwards; the template emits `| safe`.
1143        let mut prepared = value.as_object().cloned().unwrap_or_default();
1144        let cleaned = prepared
1145            .get("body")
1146            .and_then(serde_json::Value::as_str)
1147            .map(crate::markdown::sanitize_html)
1148            .unwrap_or_default();
1149        prepared.insert("body".to_owned(), serde_json::Value::String(cleaned));
1150        crate::block::render::default_render(self, &serde_json::Value::Object(prepared), ctx)
1151    }
1152}
1153
1154/// `decimal` — Like FloatBlock but the
1155/// default ships with a stable `step="any"` hint via the Float
1156/// widget. Hosts that need bounded precision pass a custom
1157/// `BlockFieldMeta` via the `with_meta` setter (chained at
1158/// registration time on a subclassed variant). Storage is the
1159/// decimal as a string so banking-grade precision round-trips
1160/// through serde without f64 loss.
1161#[derive(Default)]
1162pub struct DecimalBlock;
1163
1164impl Block for DecimalBlock {
1165    fn type_name(&self) -> &'static str {
1166        "decimal"
1167    }
1168    fn verbose_name(&self) -> &'static str {
1169        "Decimal"
1170    }
1171    fn icon(&self) -> Option<&'static str> {
1172        Some("attach_money")
1173    }
1174    fn description(&self) -> Option<&'static str> {
1175        Some("Decimal number (stored as text for precision).")
1176    }
1177    fn fields(&self) -> Vec<BlockField> {
1178        vec![BlockField::Widget {
1179            name: "value".to_owned(),
1180            label: "Value".to_owned(),
1181            widget: WidgetKind::Float,
1182            options: Vec::new(),
1183            help: Some(
1184                "Stored as a string for exact precision; the editor renders a number input."
1185                    .to_owned(),
1186            ),
1187            required: true,
1188            meta: BlockFieldMeta::default(),
1189        }]
1190    }
1191}
1192
1193/// `regex` — Text input with a pattern
1194/// validator. The default ships pattern-less (accepts anything);
1195/// hosts subclass + override `fields()` to attach a regex via
1196/// `BlockFieldMeta::default().pattern("^[A-Z]+$")`. The browser
1197/// validates on submit via HTML5 `pattern`.
1198#[derive(Default)]
1199pub struct RegexBlock;
1200
1201impl Block for RegexBlock {
1202    fn type_name(&self) -> &'static str {
1203        "regex"
1204    }
1205    fn verbose_name(&self) -> &'static str {
1206        "Regex-validated text"
1207    }
1208    fn icon(&self) -> Option<&'static str> {
1209        Some("pattern")
1210    }
1211    fn description(&self) -> Option<&'static str> {
1212        Some("Plain text validated against a regex pattern (host-configured).")
1213    }
1214    fn fields(&self) -> Vec<BlockField> {
1215        vec![BlockField::Widget {
1216            name: "value".to_owned(),
1217            label: "Value".to_owned(),
1218            widget: WidgetKind::Text,
1219            options: Vec::new(),
1220            help: Some(
1221                "Hosts wire a pattern via BlockField::widget(...).with_meta(\
1222                BlockFieldMeta::default().pattern(\"...\")). The browser \
1223                enforces it on form submit."
1224                    .to_owned(),
1225            ),
1226            required: true,
1227            meta: BlockFieldMeta::default(),
1228        }]
1229    }
1230}
1231
1232register_block!(FloatBlock);
1233register_block!(DecimalBlock);
1234register_block!(RegexBlock);
1235register_block!(RichTextBlock);
1236register_block!(TypedTableRowBlock);
1237register_block!(TypedTableBlock);
1238register_block!(TimeBlock);
1239register_block!(MultipleChoiceBlock);
1240register_block!(StaticBlock);
1241register_block!(RawHtmlBlock);
1242register_block!(PageChooserBlock);
1243register_block!(SnippetChooserBlock);
1244register_block!(DocumentChooserBlock);
1245
1246#[cfg(test)]
1247mod safe_href_tests {
1248    use super::safe_href;
1249
1250    #[test]
1251    fn script_schemes_are_dropped_however_spelled() {
1252        for bad in [
1253            "javascript:alert(1)",
1254            "  JAVASCRIPT:alert(1)",
1255            "java\tscript:alert(1)",
1256            "java\nscript:alert(1)",
1257            "\u{1}javascript:x",
1258            "vbscript:x",
1259            "data:text/html;base64,PHNjcmlwdD4=",
1260        ] {
1261            assert_eq!(safe_href(bad), None, "{bad:?}");
1262        }
1263    }
1264
1265    #[test]
1266    fn web_mail_phone_and_relative_targets_pass() {
1267        for ok in [
1268            "https://example.com",
1269            "HTTP://example.com",
1270            "mailto:a@example.com",
1271            "tel:+1555",
1272            "/about",
1273            "about/team",
1274            "#top",
1275            "?q=1",
1276            "/path:with:colons",
1277        ] {
1278            assert_eq!(safe_href(ok), Some(ok), "{ok:?}");
1279        }
1280    }
1281}
1282
1283#[cfg(test)]
1284mod raw_html_tests {
1285    use super::RawHtmlBlock;
1286    use crate::block::{Block, BlockRenderCtx};
1287
1288    /// The raw HTML block is on by default for every editor, so its
1289    /// render is what keeps an editor's markup from running script on the
1290    /// site: anything executable must be gone before the `| safe` template.
1291    #[test]
1292    fn executable_markup_is_stripped_on_render() {
1293        let mut tera = tera::Tera::default();
1294        tera.add_raw_template("blocks/raw_html.html", include_str!("../admin/templates/blocks/raw_html.html"))
1295            .expect("template");
1296        let ctx = BlockRenderCtx::new(&tera);
1297        let html = r#"<p>Hello <b>there</b></p><script>alert(1)</script><img src="x.png" onerror="alert(2)"><a href="javascript:alert(3)">x</a><iframe src="https://evil.example"></iframe><svg onload="alert(4)"></svg>"#;
1298        let out = RawHtmlBlock.render(&serde_json::json!({ "html": html }), &ctx).expect("render");
1299        assert!(out.contains("<b>there</b>"), "safe markup survives: {out}");
1300        for bad in ["<script", "alert(1)", "onerror", "javascript:", "<iframe", "onload"] {
1301            assert!(!out.contains(bad), "{bad} stripped: {out}");
1302        }
1303    }
1304}