@cosmicdrift/kumiko-samples 0.362.0 → 0.363.0

package/packages/bundled-features/src/template-resolver/template-validation.ts

@@ -0,0 +1,229 @@
+import type {
+  Registry,
+  TemplateScalarVariableDef,
+  TemplateVariableDef,
+  TemplateVariables,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { Element as ScanElement } from "happy-dom";
+import * as z from "zod";
+import { withParsedDocument } from "./document-sanitizer.js";
+import { isDocumentPlaceholderHref, isDocumentReferenceName } from "./document-schema.js";
+import type { TemplateMeta } from "./template-meta.js";
+
+export const SYSTEM_PLACEHOLDERS: ReadonlySet<string> = new Set([
+  "tenantName",
+  "signature",
+  "imprint",
+  "unsubscribeUrl",
+]);
+
+const PAGE_PLACEHOLDERS = ["page", "pages"] as const;
+const PAGED_KINDS: ReadonlySet<string> = new Set(["document-pdf", "pdf-layout"]);
+
+export function systemPlaceholdersFor(kind: string): ReadonlySet<string> {
+  return PAGED_KINDS.has(kind)
+    ? new Set([...SYSTEM_PLACEHOLDERS, ...PAGE_PLACEHOLDERS])
+    : SYSTEM_PLACEHOLDERS;
+}
+
+const BASE_RESOURCE_KEYS = ["logo"] as const;
+
+export type TemplateValidation = {
+  readonly unknown: readonly string[];
+  readonly missingRequired: readonly string[];
+  readonly used: readonly string[];
+  /** data-resource keys with no uploaded file; a warning, never a blocker. */
+  readonly unknownResources: readonly string[];
+};
+
+// Mirrors TemplateVariableDef: a stored or draft schema keeps its label and example, which the
+// preview uses as sample values.
+const variableCommon = {
+  label: z.string().optional(),
+  required: z.boolean().optional(),
+};
+const textLikeExample = z.string().optional();
+
+const scalarVariableSchema = z.discriminatedUnion("type", [
+  z.object({ ...variableCommon, type: z.literal("text"), example: textLikeExample }),
+  z.object({ ...variableCommon, type: z.literal("link"), example: textLikeExample }),
+  z.object({
+    ...variableCommon,
+    type: z.literal("money"),
+    example: z
+      .union([z.number(), z.object({ amount: z.number(), currency: z.string() })])
+      .optional(),
+  }),
+  z.object({ ...variableCommon, type: z.literal("date"), example: textLikeExample }),
+]);
+
+const variableDefSchema = z.union([
+  scalarVariableSchema,
+  z.object({
+    ...variableCommon,
+    type: z.literal("list"),
+    item: z.record(z.string(), scalarVariableSchema),
+    example: z.array(z.record(z.string(), z.unknown())).optional(),
+  }),
+]);
+
+// 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: unknown): TemplateVariableDef | null {
+  if (typeof raw === "string") return { type: "text" };
+  const parsed = variableDefSchema.safeParse(raw);
+  return parsed.success ? parsed.data : null;
+}
+
+export function resolveTemplateVariables(
+  registry: Registry,
+  slug: string,
+  variableSchema: Readonly<Record<string, unknown>>,
+): TemplateVariables {
+  const declared = registry.getAllNotifications().get(slug)?.variables;
+  return declared ?? variablesFromSchema(variableSchema);
+}
+
+export function variablesFromSchema(
+  variableSchema: Readonly<Record<string, unknown>>,
+): TemplateVariables {
+  const variables: Record<string, TemplateVariableDef> = {};
+  for (const [name, raw] of Object.entries(variableSchema)) {
+    const def = toVariableDef(raw);
+    if (def !== null) variables[name] = def;
+  }
+  return variables;
+}
+
+type Resolution = { readonly known: boolean; readonly used: string };
+
+function rootName(name: string): string {
+  return name.split(".")[0] ?? name;
+}
+
+type PlaceholderScope = {
+  readonly variables: TemplateVariables;
+  readonly systemPlaceholders: ReadonlySet<string>;
+  readonly resourceKeys: ReadonlySet<string>;
+  readonly used: Set<string>;
+  readonly unknown: Set<string>;
+  readonly unknownResources: Set<string>;
+};
+
+function listItemFields(
+  variables: TemplateVariables,
+  listName: string | null,
+): Readonly<Record<string, TemplateScalarVariableDef>> {
+  const def =
+    listName !== null && Object.hasOwn(variables, listName) ? variables[listName] : undefined;
+  return def?.type === "list" ? def.item : {};
+}
+
+function isKnownName(
+  name: string,
+  scope: PlaceholderScope,
+  itemFields: Readonly<Record<string, unknown>>,
+): Resolution {
+  const { variables } = scope;
+  const root = rootName(name);
+  if (Object.hasOwn(itemFields, name) || Object.hasOwn(itemFields, root)) {
+    return { known: true, used: "" };
+  }
+  if (scope.systemPlaceholders.has(root)) return { known: true, used: "" };
+  if (Object.hasOwn(variables, name)) return { known: true, used: name };
+  if (Object.hasOwn(variables, root)) return { known: true, used: root };
+  return { known: false, used: "" };
+}
+
+function recordName(
+  name: string,
+  itemFields: Readonly<Record<string, unknown>>,
+  scope: PlaceholderScope,
+) {
+  const resolution = isKnownName(name, scope, itemFields);
+  if (!resolution.known) scope.unknown.add(name);
+  else if (resolution.used !== "") scope.used.add(resolution.used);
+}
+
+function enclosingEachName(element: ScanElement): string | null {
+  return element.closest("tr[data-each]")?.getAttribute("data-each") ?? null;
+}
+
+function scanBodyPlaceholders(body: string, scope: PlaceholderScope): void {
+  withParsedDocument(body, (root) => {
+    for (const element of Array.from(root.querySelectorAll("tr[data-each]"))) {
+      const listName = element.getAttribute("data-each") ?? "";
+      const def = Object.hasOwn(scope.variables, listName) ? scope.variables[listName] : undefined;
+      if (def?.type === "list") scope.used.add(listName);
+      else scope.unknown.add(listName);
+    }
+    for (const element of Array.from(
+      root.querySelectorAll("span[data-variable], a[href], img[data-resource]"),
+    )) {
+      const itemFields = listItemFields(scope.variables, enclosingEachName(element));
+      const tag = element.tagName.toLowerCase();
+      if (tag === "span") {
+        recordName(element.getAttribute("data-variable") ?? "", itemFields, scope);
+      } else if (tag === "a") {
+        const href = element.getAttribute("href") ?? "";
+        if (isDocumentPlaceholderHref(href)) recordName(href.slice(2, -2), itemFields, scope);
+      } else {
+        const key = element.getAttribute("data-resource") ?? "";
+        if (!scope.resourceKeys.has(key)) scope.unknownResources.add(key);
+      }
+    }
+  });
+}
+
+const HANDLEBARS_EXPRESSION = /\{\{([^{}]*)\}\}/g;
+
+// Meta text supports only plain `{{name}}` / `{{name.field}}`; every other
+// Handlebars construct is reported as unknown so it can never reach the compiler.
+function scanMetaPlaceholders(text: string, scope: PlaceholderScope): void {
+  const leftover = text.replace(HANDLEBARS_EXPRESSION, (_match, inner: string) => {
+    const name = inner.trim();
+    if (isDocumentReferenceName(name)) recordName(name, {}, scope);
+    else scope.unknown.add(`{{${inner}}}`);
+    return "";
+  });
+  if (/[{}]/.test(leftover)) scope.unknown.add("{");
+}
+
+function metaTexts(meta: TemplateMeta | null): readonly string[] {
+  if (meta === null || !("subject" in meta)) return [];
+  return [meta.subject, ...(meta.previewText === undefined ? [] : [meta.previewText])];
+}
+
+export function validateTemplatePlaceholders(input: {
+  readonly kind: string;
+  readonly body: string;
+  readonly meta: TemplateMeta | null;
+  readonly variables: TemplateVariables;
+  /** data-resource keys with an uploaded file besides the built-in `logo`. */
+  readonly resourceKeys?: readonly string[];
+}): TemplateValidation {
+  const scope: PlaceholderScope = {
+    variables: input.variables,
+    systemPlaceholders: systemPlaceholdersFor(input.kind),
+    resourceKeys: new Set([...BASE_RESOURCE_KEYS, ...(input.resourceKeys ?? [])]),
+    used: new Set(),
+    unknown: new Set(),
+    unknownResources: new Set(),
+  };
+  scanBodyPlaceholders(input.body, scope);
+  for (const text of metaTexts(input.meta)) scanMetaPlaceholders(text, scope);
+  const missingRequired = Object.entries(input.variables)
+    .filter(([name, def]) => def.required === true && !scope.used.has(name))
+    .map(([name]) => name);
+  return {
+    unknown: [...scope.unknown].sort(),
+    missingRequired: missingRequired.sort(),
+    used: [...scope.used].sort(),
+    unknownResources: [...scope.unknownResources].sort(),
+  };
+}
+
+export function hasPlaceholderProblems(validation: TemplateValidation): boolean {
+  return validation.unknown.length > 0 || validation.missingRequired.length > 0;
+}

package/packages/bundled-features/src/template-resolver/testing.ts

@@ -79,7 +79,7 @@ export async function assertConsumerHandlesNotFound(
     await consumer.resolve({
       tenantId,
       slug,
-      kind: "mail-html",
+      kind: "mail",
       locale: "de",
     });
   } catch (e) {
@@ -105,7 +105,7 @@ export async function assertConsumerRespectsLocaleFallback(
   await seedTemplate(db, {
     tenantId: SYSTEM_TENANT_ID,
     slug,
-    kind: "notification",
+    kind: "document-pdf",
     locale: FALLBACK_LOCALE,
     scope: "system",
     content: "conformance-fallback-content",
@@ -113,7 +113,7 @@ export async function assertConsumerRespectsLocaleFallback(
   const result = await consumer.resolve({
     tenantId,
     slug,
-    kind: "notification",
+    kind: "document-pdf",
     locale: "tr",
   });
   if (result.locale !== FALLBACK_LOCALE) {
@@ -143,7 +143,7 @@ export async function assertConsumerHandlesMissingResourceKeys(
   await seedTemplate(db, {
     tenantId: SYSTEM_TENANT_ID,
     slug,
-    kind: "mail-html",
+    kind: "mail",
     locale: "de",
     scope: "system",
     linkedResources: { logo: "file_missing" },
@@ -151,7 +151,7 @@ export async function assertConsumerHandlesMissingResourceKeys(
   const template = await consumer.resolve({
     tenantId,
     slug,
-    kind: "mail-html",
+    kind: "mail",
     locale: "de",
   });
 

package/packages/bundled-features/src/template-resolver/web/client-plugin.tsx

@@ -40,6 +40,7 @@ import {
   TemplateResolverHandlers,
   TemplateResolverQueries,
 } from "../qualified-names.js";
+import { DocumentContentEditor } from "./document-editor.js";
 import { defaultTranslations } from "./i18n.js";
 
 // Exported for the unit test — groupBlocksByFolder is a pure function.
@@ -256,21 +257,22 @@ type TextBlock = {
   readonly modifiedAt: string | null;
 };
 
-// The collection's declared contentFormat ("plain" | "rich" | "markdown",
-// see ContentCollectionDefinition.contentFormat) uses a different vocabulary
+// The collection's declared contentFormat ("plain" | "rich" | "markdown" |
+// "document", see ContentCollectionDefinition.contentFormat) uses a different vocabulary
 // than the stored entry's contentFormat ("plain" | "html" | "markdown" |
-// "mjml", see CONTENT_FORMATS) — "rich" always stores HTML. Without this,
+// "mjml", see CONTENT_FORMATS) — "rich" and "document" always store HTML. Without this,
 // handleSave omitting contentFormat let the write schema's
 // contentFormatSchema.default("markdown") silently stamp every save as
 // markdown, clobbering e.g. a "plain" entry. Undefined (no collection, or
 // the collection didn't declare a format) keeps whatever was already saved
 // instead of guessing.
-function resolveWriteContentFormat(
+// Exported for the unit test — resolveWriteContentFormat is a pure function.
+export function resolveWriteContentFormat(
   collectionContentFormat: string | undefined,
   loadedContentFormat: string | undefined,
 ): string | undefined {
   if (collectionContentFormat === "plain") return "plain";
-  if (collectionContentFormat === "rich") return "html";
+  if (collectionContentFormat === "rich" || collectionContentFormat === "document") return "html";
   if (collectionContentFormat === "markdown") return "markdown";
   return loadedContentFormat;
 }
@@ -499,12 +501,13 @@ export function textBlocksClient(opts?: {
     resolvers: {
       "template-resolver:edit": TextBlockEditor,
     },
-    // The default for every "plain" collection (ai-prompt, mail-html without
+    // The default for every "plain" collection (ai-prompt, mail without
     // an explicit rich override) — an app-registered "plain" editor on
     // another clientFeature still wins, last-wins same as columnRenderers.
     contentEditors: {
       plain: PlainContentEditor,
       rich: RichContentEditor,
+      document: DocumentContentEditor,
       // ponytail: same textarea+chips as "plain" — markdown is stored as
       // text either way. Shares PlainContentEditor's fixed-DOM-id ceiling
       // (see its own file comment); swap for a live-preview widget or a

package/packages/bundled-features/src/template-resolver/web/document-editor-extensions.ts

@@ -0,0 +1,162 @@
+// @runtime client
+import type { Extensions, NodeViewRenderer } from "@tiptap/core";
+import { ListKeymap } from "@tiptap/extension-list";
+import { Dropcursor, Gapcursor, Placeholder, UndoRedo } from "@tiptap/extensions";
+import {
+  DocumentButton,
+  DocumentPageBreak,
+  DocumentResource,
+  DocumentVariable,
+  documentExtensions,
+} from "../document-schema.js";
+import type { DocumentResourcePreview } from "./document-toolbar-blocks.js";
+
+export type DocumentEditorLabels = {
+  readonly placeholder: string;
+  readonly image: string;
+  readonly pageBreak: string;
+  readonly button?: string;
+  readonly variableLabels?: Readonly<Record<string, string>>;
+  readonly systemVariables?: readonly string[];
+  readonly resourcePreviews?: Readonly<Record<string, DocumentResourcePreview>>;
+  /** Canvas chrome labels every block with its type. */
+  readonly blockLabels?: boolean;
+};
+
+function createElementWithClass<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  className: string,
+  text?: string,
+): HTMLElementTagNameMap[K] {
+  const element = document.createElement(tag);
+  element.className = className;
+  if (text !== undefined) element.textContent = text;
+  return element;
+}
+
+const CHIP_CLASS = "mx-0.5 inline-flex items-center gap-1 rounded border px-1.5 py-0.5 text-xs";
+const USER_CHIP_CLASS = `${CHIP_CLASS} border-primary/30 bg-primary/10 text-primary`;
+const SYSTEM_CHIP_CLASS = `${CHIP_CLASS} border-input bg-muted text-muted-foreground`;
+
+// The chip is display only: the stored node carries just the name, so a
+// label never reaches the document.
+export function createVariableView(
+  variableLabels: Readonly<Record<string, string>>,
+  systemVariables: readonly string[],
+): NodeViewRenderer {
+  return ({ node }) => {
+    const name = String(node.attrs["name"]);
+    const label = Object.hasOwn(variableLabels, name) ? variableLabels[name] : undefined;
+    const dom = createElementWithClass(
+      "span",
+      systemVariables.includes(name) ? SYSTEM_CHIP_CLASS : USER_CHIP_CLASS,
+    );
+    dom.contentEditable = "false";
+    dom.append(document.createTextNode(label !== undefined && label !== "" ? label : name));
+    if (label !== undefined && label !== "" && label !== name) {
+      dom.append(createElementWithClass("small", "font-mono text-[10px] opacity-75", name));
+    }
+    return { dom };
+  };
+}
+
+// Same rule the sanitizer's image handling follows: previews never carry a
+// scriptable scheme.
+const PREVIEW_SRC = /^(data:image\/(png|jpeg|gif|webp);|blob:|https:\/\/|\/)/;
+
+function createBlockLabel(text: string): HTMLSpanElement {
+  const label = createElementWithClass(
+    "span",
+    "absolute -top-2 left-2 bg-card px-1 text-[10px] font-medium uppercase tracking-wide text-muted-foreground",
+    text,
+  );
+  label.contentEditable = "false";
+  return label;
+}
+
+function createResourceView(labels: DocumentEditorLabels): NodeViewRenderer {
+  return ({ node }) => {
+    const key = String(node.attrs["resource"]);
+    const previews = labels.resourcePreviews ?? {};
+    const preview = Object.hasOwn(previews, key) ? previews[key] : undefined;
+    const dom = createElementWithClass(
+      "div",
+      "relative my-3 flex items-center gap-3 rounded border border-dashed border-input px-3 py-3 text-sm text-muted-foreground",
+    );
+    dom.contentEditable = "false";
+    if (labels.blockLabels) dom.append(createBlockLabel(labels.image));
+    if (preview !== undefined && PREVIEW_SRC.test(preview.src)) {
+      const image = createElementWithClass("img", "max-h-16 max-w-48 rounded");
+      image.src = preview.src;
+      image.alt = typeof node.attrs["alt"] === "string" ? node.attrs["alt"] : key;
+      dom.append(image);
+      dom.append(createElementWithClass("span", "text-xs", preview.caption ?? key));
+    } else {
+      dom.append(
+        createElementWithClass("span", "font-medium", labels.image),
+        createElementWithClass("code", "text-xs", key),
+      );
+    }
+    return { dom };
+  };
+}
+
+function createButtonView(buttonLabel: string): NodeViewRenderer {
+  return () => {
+    const dom = createElementWithClass(
+      "div",
+      "relative my-3 rounded border border-dashed border-input p-3",
+    );
+    const button = document.createElement("a");
+    button.setAttribute("data-button", "");
+    dom.append(createBlockLabel(buttonLabel), button);
+    return { dom, contentDOM: button };
+  };
+}
+
+function createPageBreakView(pageBreakLabel: string): NodeViewRenderer {
+  return () => {
+    const dom = createElementWithClass(
+      "div",
+      "my-3 border-t border-dashed border-input pt-1 text-center text-xs text-muted-foreground",
+      pageBreakLabel,
+    );
+    dom.contentEditable = "false";
+    return { dom };
+  };
+}
+
+// Replaced by name, not appended: the schema must keep exactly one node per
+// name, and only the editor view differs from the shared document schema.
+export function createDocumentEditorExtensions(labels: DocumentEditorLabels): Extensions {
+  const base = documentExtensions.map((extension) => {
+    switch (extension.name) {
+      case DocumentVariable.name:
+        return DocumentVariable.extend({
+          addNodeView: () =>
+            createVariableView(labels.variableLabels ?? {}, labels.systemVariables ?? []),
+        });
+      case DocumentResource.name:
+        return DocumentResource.extend({ addNodeView: () => createResourceView(labels) });
+      case DocumentButton.name:
+        return labels.blockLabels
+          ? DocumentButton.extend({ addNodeView: () => createButtonView(labels.button ?? "") })
+          : extension;
+      case DocumentPageBreak.name:
+        return DocumentPageBreak.extend({
+          addNodeView: () => createPageBreakView(labels.pageBreak),
+        });
+      default:
+        return extension;
+    }
+  });
+  // No TrailingNode: it appends an empty paragraph that breaks the HTML roundtrip.
+  return [
+    ...base,
+    UndoRedo,
+    Gapcursor,
+    Dropcursor,
+    ListKeymap,
+    Placeholder.configure({ placeholder: labels.placeholder }),
+  ];
+}

package/packages/bundled-features/src/template-resolver/web/document-editor.tsx

@@ -0,0 +1,28 @@
+// @runtime client
+//
+// Lazy boundary: tiptap only loads when a "document" collection is rendered.
+// Never import document-tiptap-editor or document-editor-extensions statically here.
+
+import { TextareaContentEditor } from "@cosmicdrift/kumiko-renderer";
+import { lazy, type ReactNode, Suspense } from "react";
+import type { DocumentEditorProps } from "./document-toolbar-blocks.js";
+
+const LazyDocumentTiptapEditor = lazy(() => import("./document-tiptap-editor.js"));
+
+export function DocumentContentEditor(props: DocumentEditorProps): ReactNode {
+  return (
+    <Suspense
+      fallback={
+        <TextareaContentEditor
+          id={props.id}
+          value={props.value}
+          onChange={props.onChange}
+          variables={props.variables}
+          readOnly={props.readOnly}
+        />
+      }
+    >
+      <LazyDocumentTiptapEditor {...props} />
+    </Suspense>
+  );
+}