@cosmicdrift/kumiko-samples 0.363.0 → 0.365.0

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

@@ -1,4 +1,8 @@
-import { parseQn, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type NotificationDefinition,
+  parseQn,
+  type Registry,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { DEFAULT_MAIL_LAYOUT_SLUG, type TemplateKind } from "./constants.js";
 
 type UsageRole = "template" | "layout";
@@ -11,27 +15,43 @@ export type TemplateUsageEntry = {
   readonly role: UsageRole;
 };
 
+/** Layout slug of the effective stored mail template, by notification qualified
+ *  name and locale. The renderer reads the layout from the stored row's meta,
+ *  so it wins over the code-registered notification meta. */
+export type EffectiveMailLayoutSlugs = ReadonlyMap<string, ReadonlyMap<string, string>>;
+
+function layoutSlugsOf(
+  qualifiedName: string,
+  notification: NotificationDefinition,
+  effectiveLayouts: EffectiveMailLayoutSlugs,
+): string[] {
+  const stored = effectiveLayouts.get(qualifiedName);
+  const locales = new Set([
+    ...Object.keys(notification.template ?? {}),
+    ...Object.keys(notification.meta ?? {}),
+    ...(stored?.keys() ?? []),
+  ]);
+  return [...locales].map(
+    (locale) =>
+      stored?.get(locale) ?? notification.meta?.[locale]?.layoutSlug ?? DEFAULT_MAIL_LAYOUT_SLUG,
+  );
+}
+
 export function collectTemplateUsage(
   registry: Registry,
   slug: string,
   kind: TemplateKind,
+  effectiveLayouts: EffectiveMailLayoutSlugs = new Map(),
 ): TemplateUsageEntry[] {
   const usedBy: TemplateUsageEntry[] = [];
   if (kind === "mail" || kind === "mail-layout") {
     for (const [qualifiedName, notification] of registry.getAllNotifications()) {
       const role: UsageRole = kind === "mail" ? "template" : "layout";
+      // Notifications without a code template are not rendered through the resolver.
       const isUsed =
         kind === "mail"
-          ? qualifiedName === slug
-          : [
-              ...new Set([
-                ...Object.keys(notification.template ?? {}),
-                ...Object.keys(notification.meta ?? {}),
-              ]),
-            ].some(
-              (locale) =>
-                (notification.meta?.[locale]?.layoutSlug ?? DEFAULT_MAIL_LAYOUT_SLUG) === slug,
-            );
+          ? qualifiedName === slug && notification.template !== undefined
+          : layoutSlugsOf(qualifiedName, notification, effectiveLayouts).includes(slug);
       if (!isUsed) continue;
       const parsed = parseQn(qualifiedName);
       usedBy.push({

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

@@ -47,6 +47,7 @@ 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("richText"), example: textLikeExample }),
   z.object({
     ...variableCommon,
     type: z.literal("money"),
@@ -127,12 +128,10 @@ function isKnownName(
 ): Resolution {
   const { variables } = scope;
   const root = rootName(name);
-  if (Object.hasOwn(itemFields, name) || Object.hasOwn(itemFields, root)) {
-    return { known: true, used: "" };
-  }
+  // Declared variables and item fields are scalars: a dotted path under one never renders a value.
+  if (Object.hasOwn(itemFields, name)) 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: "" };
 }
 
@@ -150,6 +149,11 @@ function enclosingEachName(element: ScanElement): string | null {
   return element.closest("tr[data-each]")?.getAttribute("data-each") ?? null;
 }
 
+const NAME_ATTRIBUTE_BY_TAG: Readonly<Record<string, string>> = {
+  span: "data-variable",
+  div: "data-steps",
+};
+
 function scanBodyPlaceholders(body: string, scope: PlaceholderScope): void {
   withParsedDocument(body, (root) => {
     for (const element of Array.from(root.querySelectorAll("tr[data-each]"))) {
@@ -159,12 +163,13 @@ function scanBodyPlaceholders(body: string, scope: PlaceholderScope): void {
       else scope.unknown.add(listName);
     }
     for (const element of Array.from(
-      root.querySelectorAll("span[data-variable], a[href], img[data-resource]"),
+      root.querySelectorAll("span[data-variable], div[data-steps], 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);
+      const nameAttribute = NAME_ATTRIBUTE_BY_TAG[tag];
+      if (nameAttribute !== undefined) {
+        recordName(element.getAttribute(nameAttribute) ?? "", itemFields, scope);
       } else if (tag === "a") {
         const href = element.getAttribute("href") ?? "";
         if (isDocumentPlaceholderHref(href)) recordName(href.slice(2, -2), itemFields, scope);
@@ -178,7 +183,7 @@ function scanBodyPlaceholders(body: string, scope: PlaceholderScope): void {
 
 const HANDLEBARS_EXPRESSION = /\{\{([^{}]*)\}\}/g;
 
-// Meta text supports only plain `{{name}}` / `{{name.field}}`; every other
+// Meta text supports only plain `{{name}}` references; 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) => {
@@ -192,7 +197,9 @@ function scanMetaPlaceholders(text: string, scope: PlaceholderScope): void {
 
 function metaTexts(meta: TemplateMeta | null): readonly string[] {
   if (meta === null || !("subject" in meta)) return [];
-  return [meta.subject, ...(meta.previewText === undefined ? [] : [meta.previewText])];
+  return [meta.subject, meta.previewText, meta.headerChip, meta.tone, meta.footerNote].filter(
+    (text): text is string => text !== undefined,
+  );
 }
 
 export function validateTemplatePlaceholders(input: {

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

@@ -40,7 +40,8 @@ import {
   TemplateResolverHandlers,
   TemplateResolverQueries,
 } from "../qualified-names.js";
-import { DocumentContentEditor } from "./document-editor.js";
+import { DocumentBlocksContext, DocumentContentEditor } from "./document-editor.js";
+import { documentBlocksForKind } from "./document-toolbar-blocks.js";
 import { defaultTranslations } from "./i18n.js";
 
 // Exported for the unit test — groupBlocksByFolder is a pure function.
@@ -311,6 +312,7 @@ function TextBlockEditor({
   const contentFormat = findContentFormat(features, collectionId);
   const variableExamples = findVariableExamples(features, collectionId);
   const variables = Object.keys(variableExamples);
+  const documentBlocks = documentBlocksForKind(findCollection(features, collectionId)?.kind);
   const ContentEditor = useContentEditor(contentFormat);
   const canWrite =
     user?.roles.includes("TenantAdmin") === true || user?.roles.includes("SystemAdmin") === true;
@@ -448,13 +450,15 @@ function TextBlockEditor({
             contentFormat={contentFormat}
           />
         ) : (
-          <ContentEditor
-            id={contentEditorId}
-            value={content}
-            onChange={setContent}
-            variables={variables}
-            readOnly={disabled}
-          />
+          <DocumentBlocksContext.Provider value={documentBlocks}>
+            <ContentEditor
+              id={contentEditorId}
+              value={content}
+              onChange={setContent}
+              variables={variables}
+              readOnly={disabled}
+            />
+          </DocumentBlocksContext.Provider>
         )}
       </Field>
       {saveError !== null && <Banner variant="error">{saveError}</Banner>}

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

@@ -2,20 +2,29 @@
 import type { Extensions, NodeViewRenderer } from "@tiptap/core";
 import { ListKeymap } from "@tiptap/extension-list";
 import { Dropcursor, Gapcursor, Placeholder, UndoRedo } from "@tiptap/extensions";
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
 import {
   DocumentButton,
   DocumentPageBreak,
   DocumentResource,
+  DocumentSteps,
   DocumentVariable,
   documentExtensions,
 } from "../document-schema.js";
+import { readDocumentStepsAttribute } from "../document-steps.js";
 import type { DocumentResourcePreview } from "./document-toolbar-blocks.js";
 
+const DOCUMENT_RESOURCE_SIZE_TOKEN = "{size}";
+export const DOCUMENT_BLOCK_ATTRIBUTE = "data-document-block";
+
 export type DocumentEditorLabels = {
   readonly placeholder: string;
   readonly image: string;
   readonly pageBreak: string;
   readonly button?: string;
+  readonly steps?: string;
+  /** Canvas block label of an image, e.g. "Image · inline". */
+  readonly imageBlock?: string;
   readonly variableLabels?: Readonly<Record<string, string>>;
   readonly systemVariables?: readonly string[];
   readonly resourcePreviews?: Readonly<Record<string, DocumentResourcePreview>>;
@@ -38,22 +47,36 @@ const CHIP_CLASS = "mx-0.5 inline-flex items-center gap-1 rounded border px-1.5
 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`;
 
+// A chip inside a repeat row names an item field; its label is registered as `list.field`.
+function repeatRowListAt(doc: ProseMirrorNode, position: number | undefined): string | null {
+  if (position === undefined) return null;
+  const resolved = doc.resolve(position);
+  for (let depth = resolved.depth; depth > 0; depth--) {
+    const each: unknown = resolved.node(depth).attrs["each"];
+    if (typeof each === "string" && each !== "") return each;
+  }
+  return null;
+}
+
 // 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[],
+  labelOnly = false,
 ): NodeViewRenderer {
-  return ({ node }) => {
+  return ({ node, editor, getPos }) => {
     const name = String(node.attrs["name"]);
-    const label = Object.hasOwn(variableLabels, name) ? variableLabels[name] : undefined;
+    const listName = repeatRowListAt(editor.state.doc, getPos());
+    const labelKey = listName === null ? name : `${listName}.${name}`;
+    const label = Object.hasOwn(variableLabels, labelKey) ? variableLabels[labelKey] : 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) {
+    if (!labelOnly && label !== undefined && label !== "" && label !== name) {
       dom.append(createElementWithClass("small", "font-mono text-[10px] opacity-75", name));
     }
     return { dom };
@@ -79,18 +102,46 @@ function createResourceView(labels: DocumentEditorLabels): NodeViewRenderer {
     const key = String(node.attrs["resource"]);
     const previews = labels.resourcePreviews ?? {};
     const preview = Object.hasOwn(previews, key) ? previews[key] : undefined;
+    const hasImage = preview !== undefined && PREVIEW_SRC.test(preview.src);
+    // A rendered image needs no frame until the node is selected (ProseMirror marks it).
     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",
+      hasImage
+        ? "relative my-1 flex items-center gap-2 rounded border border-transparent px-2 py-1 text-sm text-muted-foreground [.ProseMirror-focused_&.ProseMirror-selectednode]:border-dashed [.ProseMirror-focused_&.ProseMirror-selectednode]:border-input"
+        : "relative my-3 flex items-center gap-3 rounded border border-dashed border-input px-3 py-3 text-sm text-muted-foreground",
     );
+    dom.setAttribute(DOCUMENT_BLOCK_ATTRIBUTE, "");
     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");
+    if (labels.blockLabels) {
+      const label = createBlockLabel(labels.imageBlock ?? labels.image);
+      if (hasImage)
+        label.classList.add("hidden", "[.ProseMirror-focused_.ProseMirror-selectednode_&]:block");
+      dom.append(label);
+    }
+    if (hasImage) {
+      const image = createElementWithClass("img", "max-w-[180px] 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));
+      // An empty caption means "no caption", not the key.
+      const caption = preview.caption ?? key;
+      if (caption !== "") {
+        const captionElement = createElementWithClass(
+          "span",
+          "whitespace-nowrap text-[11px]",
+          caption.replace(` · ${DOCUMENT_RESOURCE_SIZE_TOKEN}`, ""),
+        );
+        // The size is only known once the browser decoded the image (possibly already, from cache).
+        const showSize = (): void => {
+          captionElement.textContent = caption.replace(
+            DOCUMENT_RESOURCE_SIZE_TOKEN,
+            `${image.naturalWidth} × ${image.naturalHeight} px`,
+          );
+        };
+        image.addEventListener("load", showSize);
+        if (image.complete && image.naturalWidth > 0) showSize();
+        dom.append(captionElement);
+      }
     } else {
       dom.append(
         createElementWithClass("span", "font-medium", labels.image),
@@ -107,6 +158,7 @@ function createButtonView(buttonLabel: string): NodeViewRenderer {
       "div",
       "relative my-3 rounded border border-dashed border-input p-3",
     );
+    dom.setAttribute(DOCUMENT_BLOCK_ATTRIBUTE, "");
     const button = document.createElement("a");
     button.setAttribute("data-button", "");
     dom.append(createBlockLabel(buttonLabel), button);
@@ -118,7 +170,7 @@ 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",
+      "my-3 border-t border-dashed border-input pt-1 text-center text-xs uppercase tracking-wide text-muted-foreground",
       pageBreakLabel,
     );
     dom.contentEditable = "false";
@@ -126,6 +178,35 @@ function createPageBreakView(pageBreakLabel: string): NodeViewRenderer {
   };
 }
 
+// A static sketch of the row: which stage is reached is only known at render time.
+function createStepsView(labels: DocumentEditorLabels): NodeViewRenderer {
+  return ({ node }) => {
+    const dom = createElementWithClass(
+      "div",
+      "relative my-3 rounded border border-dashed border-input px-3 pb-2 pt-3",
+    );
+    dom.setAttribute(DOCUMENT_BLOCK_ATTRIBUTE, "");
+    dom.contentEditable = "false";
+    const variable = String(node.attrs["variable"]);
+    const variableLabels = labels.variableLabels ?? {};
+    const variableLabel = Object.hasOwn(variableLabels, variable)
+      ? variableLabels[variable]
+      : undefined;
+    dom.append(createBlockLabel(`${labels.steps ?? "Steps"} · ${variableLabel ?? variable}`));
+    const row = createElementWithClass("div", "flex gap-1.5");
+    for (const step of readDocumentStepsAttribute(node.attrs["steps"])) {
+      const cell = createElementWithClass("div", "min-w-0 flex-1");
+      cell.append(
+        createElementWithClass("div", "h-1 rounded-full bg-primary/40"),
+        createElementWithClass("div", "truncate pt-1.5 text-xs text-muted-foreground", step.label),
+      );
+      row.append(cell);
+    }
+    dom.append(row);
+    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 {
@@ -134,7 +215,11 @@ export function createDocumentEditorExtensions(labels: DocumentEditorLabels): Ex
       case DocumentVariable.name:
         return DocumentVariable.extend({
           addNodeView: () =>
-            createVariableView(labels.variableLabels ?? {}, labels.systemVariables ?? []),
+            createVariableView(
+              labels.variableLabels ?? {},
+              labels.systemVariables ?? [],
+              labels.blockLabels === true,
+            ),
         });
       case DocumentResource.name:
         return DocumentResource.extend({ addNodeView: () => createResourceView(labels) });
@@ -142,6 +227,8 @@ export function createDocumentEditorExtensions(labels: DocumentEditorLabels): Ex
         return labels.blockLabels
           ? DocumentButton.extend({ addNodeView: () => createButtonView(labels.button ?? "") })
           : extension;
+      case DocumentSteps.name:
+        return DocumentSteps.extend({ addNodeView: () => createStepsView(labels) });
       case DocumentPageBreak.name:
         return DocumentPageBreak.extend({
           addNodeView: () => createPageBreakView(labels.pageBreak),

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

@@ -4,25 +4,35 @@
 // 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";
+import { createContext, lazy, type ReactNode, Suspense, useContext } from "react";
+import type { DocumentEditorProps, DocumentToolbarBlock } from "./document-toolbar-blocks.js";
 
 const LazyDocumentTiptapEditor = lazy(() => import("./document-tiptap-editor.js"));
 
+// The editor registry only hands ContentEditorProps to an editor, so the
+// collection's block set (mail vs. PDF) reaches it through this context. An
+// explicit `blocks` prop still wins.
+export const DocumentBlocksContext = createContext<readonly DocumentToolbarBlock[] | undefined>(
+  undefined,
+);
+
 export function DocumentContentEditor(props: DocumentEditorProps): ReactNode {
+  const contextBlocks = useContext(DocumentBlocksContext);
+  const editorProps = props.blocks === undefined ? { ...props, blocks: contextBlocks } : props;
   return (
     <Suspense
+      // Read-only without chips: a textarea would insert {{name}} text and plaintext into a document body.
       fallback={
         <TextareaContentEditor
           id={props.id}
           value={props.value}
           onChange={props.onChange}
-          variables={props.variables}
-          readOnly={props.readOnly}
+          variables={[]}
+          readOnly
         />
       }
     >
-      <LazyDocumentTiptapEditor {...props} />
+      <LazyDocumentTiptapEditor {...editorProps} />
     </Suspense>
   );
 }