@cosmicdrift/kumiko-bundled-features 0.374.0 → 0.377.0

package/dist/template-resolver/handlers/import-bundle.write.d.ts

@@ -20,6 +20,7 @@ export declare const importBundleWrite: import("@cosmicdrift/kumiko-types/define
         locales: z.ZodRecord<z.ZodString, z.ZodObject<{
             body: z.ZodString;
             meta: z.ZodOptional<z.ZodUnknown>;
+            title: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
         resources: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
             fileName: z.ZodString;

package/dist/template-resolver/handlers/patch-draft.write.d.ts

@@ -0,0 +1,66 @@
+import * as z from "zod";
+export declare const patchDraftWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"patch-draft", z.ZodObject<{
+    slug: z.ZodString;
+    kind: z.ZodEnum<{
+        "document-pdf": "document-pdf";
+        mail: "mail";
+    }>;
+    locale: z.ZodString;
+    base: z.ZodObject<{
+        scope: z.ZodEnum<{
+            system: "system";
+            tenant: "tenant";
+        }>;
+        version: z.ZodNumber;
+    }, z.core.$strip>;
+    ops: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        op: z.ZodLiteral<"insertBlock">;
+        after: z.ZodNullable<z.ZodString>;
+        block: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"paragraph">;
+            text: z.ZodString;
+            align: z.ZodOptional<z.ZodEnum<{
+                center: "center";
+                justify: "justify";
+                left: "left";
+                right: "right";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"heading">;
+            level: z.ZodNumber;
+            text: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"image">;
+            resource: z.ZodString;
+            alt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"button">;
+            text: z.ZodString;
+            href: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"divider">;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"pageBreak">;
+        }, z.core.$strip>], "type">;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"replaceText">;
+        blockId: z.ZodString;
+        find: z.ZodString;
+        replace: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"removeBlock">;
+        blockId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"setResource">;
+        blockId: z.ZodString;
+        resource: z.ZodString;
+        alt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"setMeta">;
+        meta: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"setVariable">;
+        name: z.ZodString;
+        definition: z.ZodNullable<z.ZodUnknown>;
+    }, z.core.$strip>], "op">>;
+}, z.core.$strip>, import("./template-write.ts").WrittenTemplateRow, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/template-resolver/handlers/patch-draft.write.js

@@ -0,0 +1,105 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, ValidationError, VersionConflictError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { DOCUMENT_HTML_KINDS } from "../constants.js";
+import { applyDocumentOps, documentOpsSchema } from "../document-ops.js";
+import { parseDocumentJson, serializeDocumentJson } from "../document-sanitizer.js";
+import { resolveTemplateVariables } from "../template-validation.js";
+import { loadDocumentBase } from "./document-base.js";
+import { localeSchema, templateSlugSchema } from "./shared.js";
+import { writeTemplateRow } from "./template-write.js";
+import { validateTemplateDraft } from "./validate.query.js";
+function validationFailure(issue) {
+    return writeFailure(new ValidationError({ fields: [issue] }));
+}
+export const patchDraftWrite = defineWriteHandler({
+    name: "patch-draft",
+    schema: z.object({
+        slug: templateSlugSchema,
+        kind: z.enum(DOCUMENT_HTML_KINDS),
+        locale: localeSchema,
+        base: z.object({
+            scope: z.enum(["tenant", "system"]),
+            version: z.number().int().nonnegative(),
+        }),
+        ops: documentOpsSchema,
+    }),
+    access: { roles: ["TenantAdmin", "SystemAdmin"] },
+    description: "Changes a mail or PDF document template with structured operations instead of a full rewrite and saves the result as the caller's tenant draft (never published, an active version keeps being served until publish): insertBlock after a block id (null = at the start; paragraph, heading, image, button, divider, pageBreak), replaceText inside one block (the text must occur exactly once), removeBlock, setResource on an image block, setMeta (flat merge, null removes a key) and setVariable (adds, replaces or with null removes a variable definition; refused when a notification declares the variables). Block ids and base come from document-blocks and refer to the state that was read; if the template changed since, the call fails with version_conflict and nothing is written. A patch that removes a required placeholder is refused. Returns the written row.",
+    handler: async (event, ctx) => {
+        const { slug, kind, locale, base, ops } = event.payload;
+        const loaded = await loadDocumentBase(ctx, event.user, { slug, kind, locale });
+        if (loaded === null)
+            return writeFailure(new NotFoundError("template-resource", slug));
+        if (loaded.base.scope !== base.scope || loaded.base.version !== base.version) {
+            return writeFailure(new VersionConflictError({
+                entityId: loaded.rowId,
+                expectedVersion: base.version,
+                currentVersion: loaded.base.version,
+            }));
+        }
+        const variableOpIndex = ops.findIndex((op) => op.op === "setVariable");
+        if (variableOpIndex !== -1 &&
+            ctx.registry.getAllNotifications().get(slug)?.variables !== undefined) {
+            return validationFailure({
+                path: `ops.${variableOpIndex}`,
+                code: "variables_declared_by_feature",
+                i18nKey: "templateResolver.errors.patch.variablesDeclaredByFeature",
+                params: { slug },
+            });
+        }
+        const applied = applyDocumentOps({
+            doc: parseDocumentJson(loaded.content),
+            meta: loaded.meta,
+            variableSchema: loaded.variableSchema,
+            kind,
+            ops,
+        });
+        if (!applied.ok)
+            return writeFailure(new ValidationError({ fields: applied.issues }));
+        const content = serializeDocumentJson(applied.doc);
+        const draftOf = (draftContent, meta, variableSchema) => validateTemplateDraft(ctx, event.user, {
+            slug,
+            kind,
+            contentFormat: "html",
+            content: draftContent,
+            meta,
+            variableSchema,
+            locale,
+            scope: "tenant",
+        });
+        const before = await draftOf(loaded.content, loaded.meta, loaded.variableSchema);
+        const after = await draftOf(content, applied.meta, applied.variableSchema);
+        const alreadyMissing = new Set(before.response.missingRequired);
+        const removed = after.response.missingRequired.filter((name) => !alreadyMissing.has(name));
+        if (removed.length > 0) {
+            return validationFailure({
+                path: "ops",
+                code: "required_placeholder_removed",
+                i18nKey: "templateResolver.errors.patch.requiredPlaceholderRemoved",
+                params: { names: removed },
+            });
+        }
+        return writeTemplateRow({
+            ctx,
+            user: event.user,
+            tenantId: event.user.tenantId,
+            scope: "tenant",
+            status: "draft",
+            variables: resolveTemplateVariables(ctx.registry, slug, applied.variableSchema),
+            payload: {
+                slug,
+                kind,
+                locale,
+                content,
+                contentFormat: "html",
+                variableSchema: applied.variableSchema,
+                meta: applied.meta,
+                title: loaded.title,
+                folder: loaded.folder,
+                parentTemplateId: loaded.parentTemplateId,
+            },
+            expectedVersion: loaded.base.scope === "tenant" ? loaded.base.version : null,
+        });
+    },
+});

package/dist/template-resolver/handlers/preview.query.d.ts

@@ -9,4 +9,5 @@ export declare const previewQuery: import("@cosmicdrift/kumiko-types/define-hand
     content: z.ZodOptional<z.ZodString>;
     meta: z.ZodOptional<z.ZodUnknown>;
     variableSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>, import("../template-preview.ts").TemplatePreview, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/template-resolver/handlers/preview.query.js

@@ -12,9 +12,10 @@ export const previewQuery = defineQueryHandler({
         content: z.string().max(200_000).optional(),
         meta: z.unknown().optional(),
         variableSchema: z.record(z.string(), z.unknown()).default({}),
+        variables: z.record(z.string(), z.unknown()).optional(),
     }),
     access: { roles: ["TenantAdmin", "SystemAdmin"] },
-    description: "Renders a template draft, or the stored template when no content is given, with sample values taken from the declared variable examples, without saving or sending anything: returns the mail subject, html and plain text with its inline images (a PDF template returns its body and layout regions instead), the sample values used, and checks for unresolved images, missing plain text, mail size and unused required placeholders; a draft that fails the write rules is rejected with the same problems as a save.",
+    description: "Renders a template draft, or the stored template when no content is given, with sample values taken from the declared variable examples (values passed in variables replace them and are checked against the variable schema), without saving or sending anything: returns the mail subject, html and plain text with its inline images (a PDF template returns its body and layout regions instead), the sample values used, and checks for unresolved images, missing plain text, mail size and unused required placeholders; a draft that fails the write rules is rejected with the same problems as a save.",
     handler: async (query, ctx) => {
         const outcome = await renderTemplatePreview(ctx, query.user, query.payload);
         if (!outcome.ok)

package/dist/template-resolver/handlers/send-test.write.d.ts

@@ -5,6 +5,7 @@ export declare const sendTestWrite: import("@cosmicdrift/kumiko-types/define-han
     content: z.ZodOptional<z.ZodString>;
     meta: z.ZodOptional<z.ZodUnknown>;
     variableSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     includeAttachments: z.ZodDefault<z.ZodBoolean>;
     prefixSubject: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>, {

package/dist/template-resolver/handlers/send-test.write.js

@@ -31,12 +31,13 @@ export const sendTestWrite = defineWriteHandler({
         content: z.string().max(200_000).optional(),
         meta: z.unknown().optional(),
         variableSchema: z.record(z.string(), z.unknown()).default({}),
+        variables: z.record(z.string(), z.unknown()).optional(),
         includeAttachments: z.boolean().default(true),
         prefixSubject: z.boolean().default(true),
     }),
     access: { roles: ["TenantAdmin", "SystemAdmin"] },
     rateLimit: { per: "user+handler", ...TEST_MAIL_RATE_LIMIT },
-    description: "Sends the rendered preview of a mail template draft, or of the stored template when no content is given, to the calling user's own address with the subject prefixed by [TEST] unless prefixSubject is false, carrying the inline images and, unless includeAttachments is false, the files attached to the template; there is no recipient input, the sample values come from the declared variable examples, and a draft that fails the write rules is rejected without sending.",
+    description: "Sends the rendered preview of a mail template draft, or of the stored template when no content is given, to the calling user's own address with the subject prefixed by [TEST] unless prefixSubject is false, carrying the inline images and, unless includeAttachments is false, the files attached to the template; there is no recipient input, the sample values come from the declared variable examples unless variables replaces them (checked against the variable schema), and a draft that fails the write rules is rejected without sending.",
     handler: async (event, ctx) => {
         const { includeAttachments, prefixSubject, ...previewPayload } = event.payload;
         const outcome = await renderTemplatePreview(ctx, event.user, {

package/dist/template-resolver/handlers/template-write.d.ts

@@ -30,6 +30,8 @@ export type TemplateRowWrite = {
     readonly status: "draft" | "active";
     readonly variables: TemplateVariables;
     readonly payload: TemplateRowPayload;
+    /** The row version the edit was made against; null means no own row may exist yet. */
+    readonly expectedVersion?: number | null;
 };
 export declare function refuseTenantScopeUnderSystemTenant(scope: TemplateWriteScope, tenantId: string): WriteResult<never> | null;
 export declare function refuseSystemOnlyTenantOverride(registry: Registry, scope: TemplateWriteScope, slug: string, kind: string): WriteFailure | null;

package/dist/template-resolver/handlers/template-write.js

@@ -1,6 +1,6 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import { SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
-import { AccessDeniedError, ValidationError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
+import { AccessDeniedError, ValidationError, VersionConflictError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
 import { requireForTenant } from "../../shared/index.js";
 import { TemplateResolverErrors } from "../qualified-names.js";
 import { templateResourcesTable } from "../table.js";
@@ -67,6 +67,15 @@ function updateChanges(existing, status, fields) {
         }
         : { draft };
 }
+function versionConflictFor(expectedVersion, existing, slug) {
+    if (expectedVersion === undefined || (existing?.version ?? null) === expectedVersion)
+        return null;
+    return writeFailure(new VersionConflictError({
+        entityId: existing?.id ?? slug,
+        expectedVersion: expectedVersion ?? 0,
+        currentVersion: existing?.version ?? 0,
+    }));
+}
 // Shared by every template write: validate through the one pipeline, then
 // create or update the (tenant, slug, kind, locale) row via the event-store
 // executor. linkedResources is never part of an update; resources are attached
@@ -109,10 +118,13 @@ export async function writeTemplateRow(args) {
         parentTemplateId: payload.parentTemplateId ?? null,
         status,
     };
+    const conflict = versionConflictFor(args.expectedVersion, existing, payload.slug);
+    if (conflict !== null)
+        return conflict;
     if (existing) {
         const result = await executor.update({
             id: existing.id,
-            version: existing.version,
+            version: args.expectedVersion ?? existing.version,
             changes: updateChanges(existing, status, fields),
         }, user, db, { streamTenantId });
         if (!result.isSuccess)

package/dist/template-resolver/handlers/validate.query.d.ts

@@ -12,12 +12,18 @@ type TemplateDraftInput = {
     readonly locale?: string | undefined;
     readonly scope: TemplateWriteScope;
 };
+export declare function knownResourceKeysFor(ctx: HandlerContext, user: SessionUser, where: {
+    readonly slug: string;
+    readonly kind: string;
+    readonly scope: TemplateWriteScope;
+    readonly locale: string | undefined;
+}): Promise<string[]>;
 export declare function validateTemplateDraft(ctx: HandlerContext, user: SessionUser, payload: TemplateDraftInput): Promise<{
     response: {
         canSave: boolean;
         canPublish: boolean;
-        issues: import("@cosmicdrift/kumiko-headless").FieldIssue[];
-        publishIssues: import("@cosmicdrift/kumiko-headless").FieldIssue[];
+        issues: import("@cosmicdrift/kumiko-framework/errors").FieldIssue[];
+        publishIssues: import("@cosmicdrift/kumiko-framework/errors").FieldIssue[];
         used: string[];
         unknown: string[];
         missingRequired: string[];
@@ -58,8 +64,8 @@ export declare const validateQuery: import("@cosmicdrift/kumiko-types/define-han
 }, z.core.$strip>, {
     canSave: boolean;
     canPublish: boolean;
-    issues: import("@cosmicdrift/kumiko-headless").FieldIssue[];
-    publishIssues: import("@cosmicdrift/kumiko-headless").FieldIssue[];
+    issues: import("@cosmicdrift/kumiko-framework/errors").FieldIssue[];
+    publishIssues: import("@cosmicdrift/kumiko-framework/errors").FieldIssue[];
     used: string[];
     unknown: string[];
     missingRequired: string[];

package/dist/template-resolver/handlers/validate.query.js

@@ -18,13 +18,10 @@ async function knownResourceKeys(db, where) {
     });
     return rows.flatMap((row) => imageResourceKeysOf(row.linkedResources));
 }
-// The dry run of the write pipeline; preview feeds on the evaluation, validate returns the response.
-export async function validateTemplateDraft(ctx, user, payload) {
-    const variables = resolveTemplateVariables(ctx.registry, payload.slug, payload.variableSchema);
-    const { slug, kind, locale } = payload;
-    // The dry run must not promise what the caller's write handlers would refuse.
-    const scope = isSystemAdmin(user) ? payload.scope : "tenant";
-    const known = [
+// Image keys the editor may reference: the system rows plus, for a tenant write, the caller's own.
+export async function knownResourceKeysFor(ctx, user, where) {
+    const { slug, kind, scope, locale } = where;
+    return [
         ...(await knownResourceKeys(ctx.db, {
             tenantId: SYSTEM_TENANT_ID,
             slug,
@@ -36,6 +33,14 @@ export async function validateTemplateDraft(ctx, user, payload) {
             ? await knownResourceKeys(ctx.db, { tenantId: user.tenantId, slug, kind, scope, locale })
             : []),
     ];
+}
+// The dry run of the write pipeline; preview feeds on the evaluation, validate returns the response.
+export async function validateTemplateDraft(ctx, user, payload) {
+    const variables = resolveTemplateVariables(ctx.registry, payload.slug, payload.variableSchema);
+    const { slug, kind, locale } = payload;
+    // The dry run must not promise what the caller's write handlers would refuse.
+    const scope = isSystemAdmin(user) ? payload.scope : "tenant";
+    const known = await knownResourceKeysFor(ctx, user, { slug, kind, scope, locale });
     const evaluation = evaluateTemplateWrite({
         kind,
         scope,

package/dist/template-resolver/{web/placeholder-text.js → placeholder-text.js}

@@ -1,4 +1,4 @@
-import { isDocumentReferenceName } from "../document-schema.js";
+import { isDocumentReferenceName } from "./document-schema.js";
 const PLACEHOLDER_TOKEN = /\{\{([^{}]*)\}\}/g;
 // Names the schema refuses stay plain text, so a typo never becomes a chip
 // that the server would reject.

package/dist/template-resolver/qualified-names.d.ts

@@ -17,6 +17,7 @@ export declare const TemplateResolverHandlers: {
     readonly resourceRemove: "template-resolver:write:resource-remove";
     readonly resourceLinkPdf: "template-resolver:write:resource-link-pdf";
     readonly sendTest: "template-resolver:write:send-test";
+    readonly patchDraft: "template-resolver:write:patch-draft";
 };
 export declare const TemplateResolverQueries: {
     readonly findById: "template-resolver:query:find-by-id";
@@ -28,6 +29,7 @@ export declare const TemplateResolverQueries: {
     readonly diffToSystem: "template-resolver:query:diff-to-system";
     readonly validate: "template-resolver:query:validate";
     readonly preview: "template-resolver:query:preview";
+    readonly documentBlocks: "template-resolver:query:document-blocks";
     readonly exportBundle: "template-resolver:query:export-bundle";
     readonly bySlug: "template-resolver:query:by-slug";
     readonly byTenant: "template-resolver:query:by-tenant";

package/dist/template-resolver/qualified-names.js

@@ -19,6 +19,7 @@ export const TemplateResolverHandlers = {
     resourceRemove: "template-resolver:write:resource-remove",
     resourceLinkPdf: "template-resolver:write:resource-link-pdf",
     sendTest: "template-resolver:write:send-test",
+    patchDraft: "template-resolver:write:patch-draft",
 };
 export const TemplateResolverQueries = {
     findById: "template-resolver:query:find-by-id",
@@ -30,6 +31,7 @@ export const TemplateResolverQueries = {
     diffToSystem: "template-resolver:query:diff-to-system",
     validate: "template-resolver:query:validate",
     preview: "template-resolver:query:preview",
+    documentBlocks: "template-resolver:query:document-blocks",
     exportBundle: "template-resolver:query:export-bundle",
     // Public pair — anonymous-reachable, kind pinned to text-block.
     bySlug: "template-resolver:query:by-slug",

package/dist/template-resolver/seeding.d.ts

@@ -15,6 +15,7 @@ export type SeedSystemTemplateOptions = {
      *  system admin uploaded through resource-upload. */
     readonly linkedResources?: Record<string, string>;
     readonly meta?: unknown;
+    readonly title?: string;
     readonly parentTemplateId?: string | null;
     readonly by?: SessionUser;
     readonly ifExists?: SeedIfExists;

package/dist/template-resolver/seeding.js

@@ -81,7 +81,7 @@ export async function seedSystemTemplate(db, opts) {
         variableSchema,
         ...(linkedResources !== undefined && { linkedResources }),
         meta,
-        title: null,
+        title: opts.title ?? null,
         folder: null,
         scope: "system",
         parentTemplateId,
@@ -171,6 +171,7 @@ export async function seedSystemTemplateBundle(db, bundle, opts = {}) {
             contentFormat: bundle.contentFormat,
             variableSchema: bundle.variableSchema ?? {},
             meta: entry.meta,
+            ...(entry.title !== undefined ? { title: entry.title } : {}),
             ...(opts.by !== undefined ? { by: opts.by } : {}),
             ...(opts.ifExists !== undefined ? { ifExists: opts.ifExists } : {}),
         });

package/dist/template-resolver/table.d.ts

@@ -14,7 +14,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -66,7 +66,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -89,7 +89,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -112,7 +112,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -245,7 +245,7 @@ export declare const templateResourceEntity: import("@cosmicdrift/kumiko-types/f
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -343,7 +343,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -395,7 +395,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -418,7 +418,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -441,7 +441,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -574,7 +574,7 @@ export declare const templateResourcesTable: import("@cosmicdrift/kumiko-framewo
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {

package/dist/template-resolver/template-bundle.d.ts

@@ -19,6 +19,7 @@ export declare const templateBundleSchema: z.ZodObject<{
     locales: z.ZodRecord<z.ZodString, z.ZodObject<{
         body: z.ZodString;
         meta: z.ZodOptional<z.ZodUnknown>;
+        title: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     resources: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         fileName: z.ZodString;

package/dist/template-resolver/template-bundle.js

@@ -33,7 +33,12 @@ const bundleResourceSchema = z
     .strict();
 const pdfAttachmentLinkBodySchema = templatePdfAttachmentLinkSchema.omit({ kind: true });
 const bundleLocaleEntrySchema = z
-    .object({ body: z.string().max(200_000), meta: z.unknown().optional() })
+    .object({
+    body: z.string().max(200_000),
+    meta: z.unknown().optional(),
+    // Shown in the template overview instead of the slug; one per locale, so it is translated.
+    title: z.string().min(1).max(200).optional(),
+})
     .strict();
 export const templateBundleSchema = z
     .object({

package/dist/template-resolver/template-preview.d.ts

@@ -1,4 +1,4 @@
-import type { HandlerContext, SessionUser, TemplateVariables } from "@cosmicdrift/kumiko-framework/engine";
+import { type HandlerContext, type SessionUser, type TemplateVariables } from "@cosmicdrift/kumiko-framework/engine";
 import { type KumikoError } from "@cosmicdrift/kumiko-framework/errors";
 import { type MailAttachmentRef } from "../renderer-foundation/index.ts";
 import { type TemplateScope } from "./constants.ts";
@@ -41,6 +41,8 @@ export type TemplatePreviewInput = {
     readonly content?: string | undefined;
     readonly meta?: unknown;
     readonly variableSchema: Readonly<Record<string, unknown>>;
+    /** Replaces the declared example values for the named variables. */
+    readonly variables?: Readonly<Record<string, unknown>> | undefined;
 };
 type ValidationResponse = Awaited<ReturnType<typeof validateTemplateDraft>>["response"];
 export type TemplatePreview = {
@@ -59,6 +61,7 @@ export type TemplatePreview = {
         readonly scope: TemplateScope;
         readonly version: number;
     } | null;
+    /** The values the preview was actually rendered with: examples plus any overrides. */
     readonly sampleValues: Readonly<Record<string, unknown>>;
     readonly checks: readonly PreviewCheck[];
     readonly validation: ValidationResponse;

package/dist/template-resolver/template-preview.js

@@ -1,8 +1,10 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
-import { NotFoundError, UnprocessableError, ValidationError, } from "@cosmicdrift/kumiko-framework/errors";
+import { templateVariablesToZod, } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, UnprocessableError, ValidationError, validationErrorFromZod, } from "@cosmicdrift/kumiko-framework/errors";
 import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
 import { createI18n } from "@cosmicdrift/kumiko-framework/i18n";
-import { escapeHtml } from "@cosmicdrift/kumiko-headless";
+import { escapeHtml } from "@cosmicdrift/kumiko-renderer/headless";
+import * as z from "zod";
 import { createEmailAttachmentReader, createTemplateMailRenderer } from "../delivery/index.js";
 import { fileContextForTenant } from "../file-foundation/index.js";
 import { collectRendererPlugins, createRendererFoundationApi, RendererError, } from "../renderer-foundation/index.js";
@@ -413,7 +415,18 @@ export async function renderTemplatePreview(ctx, user, input) {
         return failed(new ValidationError({ fields: [...evaluation.issues] }));
     const content = evaluation.content ?? "";
     const meta = parseTemplateMeta(input.kind, parseStoredJson(evaluation.metaJson));
-    const sampleValues = sampleValuesFor(validation.variables, labelTextFor(ctx, input.locale));
+    const exampleValues = sampleValuesFor(validation.variables, labelTextFor(ctx, input.locale));
+    let sampleValues = exampleValues;
+    if (input.variables !== undefined) {
+        const overrides = z.object({
+            variables: templateVariablesToZod(validation.variables).partial().strict(),
+        });
+        const checked = overrides.safeParse({ variables: input.variables });
+        if (!checked.success)
+            return failed(validationErrorFromZod(checked.error));
+        // Original values, not the parse result: parsing would strip keys inside list rows.
+        sampleValues = { ...exampleValues, ...input.variables };
+    }
     if (input.kind === "document-pdf") {
         return renderDocumentPreview(ctx, user, {
             input,

package/dist/template-resolver/template-validation.d.ts

@@ -1,4 +1,4 @@
-import type { Registry, TemplateVariables } from "@cosmicdrift/kumiko-framework/engine";
+import type { Registry, TemplateVariableDef, TemplateVariables } from "@cosmicdrift/kumiko-framework/engine";
 import type { TemplateMeta } from "./template-meta.ts";
 export declare const SYSTEM_PLACEHOLDERS: ReadonlySet<string>;
 export declare function systemPlaceholdersFor(kind: string): ReadonlySet<string>;
@@ -9,6 +9,7 @@ export type TemplateValidation = {
     /** data-resource keys with no uploaded file; a warning, never a blocker. */
     readonly unknownResources: readonly string[];
 };
+export declare function toVariableDef(raw: unknown): TemplateVariableDef | null;
 export declare function resolveTemplateVariables(registry: Registry, slug: string, variableSchema: Readonly<Record<string, unknown>>): TemplateVariables;
 export declare function variablesFromSchema(variableSchema: Readonly<Record<string, unknown>>): TemplateVariables;
 export declare function validateTemplatePlaceholders(input: {

package/dist/template-resolver/template-validation.js

@@ -48,7 +48,7 @@ const variableDefSchema = z.union([
 // A stored variableSchema value is either a bare string (legacy "this is a text
 // variable") or a TemplateVariableDef object; anything else is not declared and
 // therefore shows up as an unknown placeholder instead of being guessed at.
-function toVariableDef(raw) {
+export function toVariableDef(raw) {
     if (typeof raw === "string")
         return { type: "text" };
     const parsed = variableDefSchema.safeParse(raw);