/* Copyright 2026 Rhett Creighton - Apache License 2.0
 *
 * HTML template engine with Mustache-style variable substitution.
 *
 * Syntax:
 *   {{key}}        HTML-escaped substitution
 *   {{{key}}}      Raw (unescaped) substitution
 *   {{> name}}     Partial include (renders another template inline)
 *
 * Partials inherit the parent's variables. Max 4 levels of nesting. */

#ifndef ZCL_UTIL_TEMPLATE_H
#define ZCL_UTIL_TEMPLATE_H

#include <stddef.h>

struct template_var {
    const char *key;
    const char *value;
};

/* Partial registry entry: maps a name to a template string. */
struct template_partial {
    const char *name;     /* lowercase with hyphens: "breadcrumb" */
    const char *tmpl;     /* pointer to TMPL_* constant */
};

/* Register the partial lookup table (generated by gen_templates).
 * Call once at startup. Thread-safe after initialization. */
void template_register_partials(const struct template_partial *partials,
                                size_t count);

/* Render template with variable substitutions.
 * {{key}} — HTML-escaped substitution.
 * {{{key}}} — raw (unescaped) substitution.
 * {{> name}} — inline partial (inherits vars, max 4 depth).
 * Missing keys leave the placeholder unchanged.
 * Returns bytes written to out (excluding NUL), or 0 on error. */
size_t template_render(const char *tmpl,
                       const struct template_var *vars, size_t num_vars,
                       char *out, size_t out_max);

/* Escape HTML special characters (< > & " ') to prevent XSS.
 * Writes at most max-1 bytes + NUL terminator.
 * Returns bytes written (excluding NUL). */
size_t html_escape(char *dst, size_t max, const char *src);

#endif /* ZCL_UTIL_TEMPLATE_H */
