feat(postcard): sample values, file hashes, index sync and the draft editor

- sample.<path> header keys and a parse-tree walker that fills every other
  variable with a visible [path] placeholder, nested fields and range
  targets included
- every file entry carries the sha256 of its CRLF-normalized text; the
  catalog lists its files (Templates, Layouts, Partials) for admin code
- SyncIndex upserts one index row per file and never touches the override
  columns of a customized row; ResetOverride returns a row to its file
- Editor validates, previews and test-sends a template, layout or partial
  draft through the render path of Send and reports field and rule
- pact.RowStateCustomized and pact.RowStateOutdated

Plan 35-01, task 4.
This commit is contained in:
Jakub Zych
2026-11-13 10:57:05 +01:00
parent 5df1ec27cf
commit 495319ee21
11 changed files with 2128 additions and 42 deletions

View File

@@ -61,6 +61,22 @@ Three layouts are available to every plugin's templates without declaring an ali
A plugin's own alias wins over `system` and `minimal`; `default` cannot be redefined.
## Sample values for previews
A preview of a template has no caller to pass its variables. A template can therefore give sample values in its header, one key per variable: `sample.` followed by the variable's path, in the variable's own case.
```text
subject = "Your order {{ .order.code }}"
sample.name = "Ada"
sample.order.code = "ZAM-1"
==
Hi {{ .name }}, we received the payment for **{{ .order.code }}** from {{ .company }}.
```
The keys are optional and sending ignores them. Where a preview finds no sample, it shows the variable's path in square brackets, so the body above previews as "Hi Ada, we received the payment for **ZAM-1** from [company]." Nested fields and lists work without samples too: `{{ range .order.items }}{{ .description }}{{ end }}` previews one item, `[order.items.description]`. Saving an edited template runs the same render, so an edit that uses a variable the plugin never passes still shows up as a placeholder, not as an error.
Previews, the checks on save and test sends are `postcard.Editor`; see the [postcard README](../../modules/postcard/README.md) for its API.
## Sending
At boot, `postcard.Activate` publishes one `postcard.Mailer` on the application, and `postcard.BootPlugin` registers each plugin's templates as it boots. Look the mailer up with `app.Lookup[postcard.Mailer]()` and send a `postcard.Message` with the template name, the recipients and the variables. Tests build the catalog and a memory driver directly, and read back what was sent: