@cosmicdrift/kumiko-document-designer 0.0.0-stage → 0.364.0

package/dist/web/types.d.ts

@@ -0,0 +1,126 @@
+import type { FieldIssue } from "@cosmicdrift/kumiko-headless";
+import type { TemplateDiff } from "./layout-types.js";
+export type TemplateScope = "system" | "tenant";
+export type TemplateStatus = "draft" | "active" | "archived";
+export declare const DOCUMENT_PDF_KIND: "document-pdf";
+export declare const PDF_LAYOUT_KIND: "pdf-layout";
+export declare const DEFAULT_LAYOUT_SLUG = "default";
+export type TemplateListRow = {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly slug: string;
+    readonly kind: string;
+    readonly locale: string;
+    readonly scope: TemplateScope;
+    readonly status: TemplateStatus;
+    readonly contentFormat: string;
+    readonly modifiedAt: string | null;
+};
+export type TemplateDetail = {
+    readonly id: string;
+    readonly version: number;
+    readonly tenantId: string;
+    readonly slug: string;
+    readonly kind: string;
+    readonly locale: string;
+    readonly content: string;
+    readonly contentFormat: string;
+    readonly variableSchema: string | null;
+    readonly linkedResources: string | null;
+    readonly meta: string | null;
+    readonly scope: TemplateScope;
+    readonly parentTemplateId: string | null;
+    readonly status: TemplateStatus;
+    readonly modifiedAt: string | null;
+    readonly active?: ServedVersionView | null;
+};
+/** The version the resolver serves while a draft is open beside it. */
+export type ServedVersionView = {
+    readonly version: number;
+    readonly since: string;
+};
+export type VariableType = "text" | "link" | "money" | "date" | "list";
+export type VariableInfo = {
+    readonly type: VariableType;
+    readonly label?: string;
+    readonly required?: boolean;
+    readonly item?: Readonly<Record<string, {
+        readonly type: VariableType;
+        readonly label?: string;
+    }>>;
+};
+export type ValidationWarning = {
+    readonly code: string;
+    readonly detail: string;
+    readonly i18nKey: string;
+};
+export type ValidationResult = {
+    readonly canSave: boolean;
+    readonly canPublish: boolean;
+    readonly issues: readonly FieldIssue[];
+    readonly publishIssues: readonly FieldIssue[];
+    readonly used: readonly string[];
+    readonly unknown: readonly string[];
+    readonly missingRequired: readonly string[];
+    readonly warnings: readonly ValidationWarning[];
+    readonly variables: Readonly<Record<string, VariableInfo>>;
+    readonly systemPlaceholders: readonly string[];
+};
+export type LayoutRegionsHtml = {
+    readonly header: string;
+    readonly signature: string;
+    readonly footer: string;
+};
+export type PreviewResult = {
+    readonly layout: {
+        readonly slug: string;
+        readonly scope: TemplateScope;
+        readonly html: string;
+        readonly regions: LayoutRegionsHtml;
+    } | null;
+};
+export type PuppeteerStatus = {
+    readonly available: true;
+} | {
+    readonly available: false;
+    readonly error?: string;
+    readonly message?: string;
+};
+export type PdfPreviewResult = {
+    readonly fileName: string;
+    readonly pdfBase64: string;
+    readonly pageCount: number;
+    readonly sizeBytes: number;
+    readonly durationMs: number;
+};
+export type TenantOverrideRow = {
+    readonly tenantId: string;
+    readonly tenantName: string;
+    readonly templateId: string;
+    readonly locale: string;
+    readonly status: "active" | "draft";
+    readonly version: number;
+    readonly changedAt: string;
+    readonly changedBy: string | null;
+};
+export type TenantOverrides = {
+    readonly activeOverrides: number;
+    readonly draftOverrides: number;
+    readonly totalTenants: number | null;
+    readonly rows: readonly TenantOverrideRow[];
+    readonly diff: TemplateDiff | null;
+};
+export type SaveResult = {
+    readonly id: string;
+    readonly slug: string;
+    readonly isNew: boolean;
+};
+export type TemplateUsage = {
+    readonly usedBy: readonly {
+        readonly qualifiedName: string;
+        readonly feature: string;
+        readonly notification: string;
+        readonly trigger: string | null;
+        readonly role: string;
+    }[];
+};

package/dist/web/types.js

@@ -0,0 +1,3 @@
+export const DOCUMENT_PDF_KIND = "document-pdf";
+export const PDF_LAYOUT_KIND = "pdf-layout";
+export const DEFAULT_LAYOUT_SLUG = "default";

package/dist/web/use-insert-targets.d.ts

@@ -0,0 +1,9 @@
+import type { DocumentEditorHandle } from "@cosmicdrift/kumiko-bundled-features/template-resolver/web";
+export type InsertField = "subject" | "previewText" | "body" | "title" | "author";
+export type InsertTargets = {
+    readonly register: (field: InsertField) => (handle: DocumentEditorHandle) => void;
+    readonly markFocused: (field: InsertField) => () => void;
+    readonly insertPlaceholder: (name: string) => void;
+    readonly insertResource: (key: string) => void;
+};
+export declare function useInsertTargets(): InsertTargets;

package/dist/web/use-insert-targets.js

@@ -0,0 +1,17 @@
+import { useRef } from "react";
+// The editors are lazy and report their handle once loaded; the rails insert into whichever
+// field had focus last (the content when none had).
+export function useInsertTargets() {
+    const handles = useRef({});
+    const lastFocused = useRef("body");
+    return {
+        register: (field) => (handle) => {
+            handles.current[field] = handle;
+        },
+        markFocused: (field) => () => {
+            lastFocused.current = field;
+        },
+        insertPlaceholder: (name) => handles.current[lastFocused.current]?.insertPlaceholder(name),
+        insertResource: (key) => handles.current.body?.insertResource(key),
+    };
+}

package/dist/web/use-mail-persistence.d.ts

@@ -0,0 +1,14 @@
+import type { MailDraft, TemplateRowView } from "./mail-types.js";
+export type MailPersistence = {
+    readonly save: (draft: MailDraft, publish: boolean) => Promise<boolean>;
+    readonly busy: boolean;
+    readonly error: string | null;
+    readonly clearError: () => void;
+};
+export declare function useMailPersistence(args: {
+    readonly slug: string;
+    readonly locale: string;
+    readonly title: string;
+    readonly isSystemAdmin: boolean;
+    readonly row: TemplateRowView | null;
+}): MailPersistence;

package/dist/web/use-mail-persistence.js

@@ -0,0 +1,49 @@
+// @runtime client
+import { TemplateResolverHandlers } from "@cosmicdrift/kumiko-bundled-features/template-resolver/web";
+import { useMutation, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { useState } from "react";
+import { errorTextWithFieldIssues } from "./field-issue-text.js";
+import { buildMeta, parseJsonRecord } from "./mail-draft.js";
+// One write for save and publish. The overview title is passed on every write because the
+// upsert replaces a missing title with null and find-by-id does not return it.
+export function useMailPersistence(args) {
+    const t = useTranslation();
+    const upsertTenant = useMutation(TemplateResolverHandlers.upsertTenant);
+    const upsertSystem = useMutation(TemplateResolverHandlers.upsertSystem);
+    const publishSystem = useMutation(TemplateResolverHandlers.publishSystem);
+    const [error, setError] = useState(null);
+    const save = async (draft, publish) => {
+        setError(null);
+        const base = {
+            slug: args.slug,
+            kind: "mail",
+            locale: args.locale,
+            title: args.title,
+            content: draft.body,
+            contentFormat: "html",
+            meta: buildMeta(draft),
+            variableSchema: parseJsonRecord(args.row?.variableSchema),
+        };
+        const saved = args.isSystemAdmin
+            ? await upsertSystem.mutate(base)
+            : await upsertTenant.mutate({ ...base, status: publish ? "active" : "draft" });
+        if (!saved.isSuccess) {
+            setError(errorTextWithFieldIssues(saved.error, t));
+            return false;
+        }
+        if (args.isSystemAdmin && publish) {
+            const published = await publishSystem.mutate({ id: saved.data.id });
+            if (!published.isSuccess) {
+                setError(errorTextWithFieldIssues(published.error, t));
+                return false;
+            }
+        }
+        return true;
+    };
+    return {
+        save,
+        busy: upsertTenant.pending || upsertSystem.pending || publishSystem.pending,
+        error,
+        clearError: () => setError(null),
+    };
+}

package/dist/web/use-overview-rows.d.ts

@@ -0,0 +1,7 @@
+import { type OverviewRowView } from "./overview-row.js";
+export type OverviewRows = {
+    readonly rows: readonly OverviewRowView[];
+    readonly loaded: boolean;
+    readonly refetch: () => Promise<void>;
+};
+export declare function useOverviewRows(kind: string, search?: string): OverviewRows;

package/dist/web/use-overview-rows.js

@@ -0,0 +1,19 @@
+// @runtime client
+import { TemplateResolverQueries } from "@cosmicdrift/kumiko-bundled-features/template-resolver/web";
+import { useQuery } from "@cosmicdrift/kumiko-renderer";
+import { parseOverviewRow } from "./overview-row.js";
+// One overview row per slug and kind; the filter is applied on the server.
+export function useOverviewRows(kind, search) {
+    const query = useQuery(TemplateResolverQueries.overview, {
+        filters: [{ field: "kind", op: "in", value: [kind] }],
+        limit: 200,
+        ...(search !== undefined && { search }),
+    });
+    return {
+        rows: (query.data?.rows ?? []).flatMap((row) => parseOverviewRow(row) ?? []),
+        loaded: query.data !== null,
+        refetch: async () => {
+            await query.refetch();
+        },
+    };
+}

package/dist/web/use-own-address.d.ts

@@ -0,0 +1,5 @@
+export type OwnAddress = {
+    readonly email: string | null;
+    readonly profileScreenId: string | null;
+};
+export declare function useOwnAddress(): OwnAddress;

package/dist/web/use-own-address.js

@@ -0,0 +1,14 @@
+// @runtime client
+import { useAppFeatures, useQuery } from "@cosmicdrift/kumiko-renderer";
+import { PROFILE_FEATURE_NAME, PROFILE_SCREEN_ID, USER_ME_QUERY_QN } from "../constants.js";
+export function useOwnAddress() {
+    const features = useAppFeatures();
+    const me = useQuery(USER_ME_QUERY_QN, {});
+    const email = me.data?.email;
+    const hasProfileScreen = features.some((feature) => feature.featureName === PROFILE_FEATURE_NAME &&
+        feature.screens.some((screen) => screen.id === PROFILE_SCREEN_ID));
+    return {
+        email: typeof email === "string" && email !== "" ? email : null,
+        profileScreenId: hasProfileScreen ? PROFILE_SCREEN_ID : null,
+    };
+}

package/dist/web/use-settled-value.d.ts

@@ -0,0 +1,2 @@
+export declare const SETTLE_DELAY_MS = 400;
+export declare function useSettledValue<T>(initial: T): readonly [T, (next: T) => void];

package/dist/web/use-settled-value.js

@@ -0,0 +1,18 @@
+// @runtime client
+import { useCallback, useRef, useState } from "react";
+export const SETTLE_DELAY_MS = 400;
+// Handler-driven debounce: the timer starts in the change handler, so no effect is needed.
+// A timer that fires after unmount only sets state on an unmounted component, which is a no-op.
+export function useSettledValue(initial) {
+    const [settled, setSettled] = useState(initial);
+    const timer = useRef(null);
+    const push = useCallback((next) => {
+        if (timer.current !== null)
+            clearTimeout(timer.current);
+        timer.current = setTimeout(() => {
+            timer.current = null;
+            setSettled(next);
+        }, SETTLE_DELAY_MS);
+    }, []);
+    return [settled, push];
+}

package/dist/web/use-test-mail.d.ts

@@ -0,0 +1,15 @@
+export type TestMailState = {
+    readonly kind: "idle";
+} | {
+    readonly kind: "sent";
+    readonly subject: string;
+} | {
+    readonly kind: "error";
+    readonly text: string;
+};
+export type TestMail = {
+    readonly state: TestMailState;
+    readonly pending: boolean;
+    readonly send: (payload: Readonly<Record<string, unknown>>) => Promise<void>;
+};
+export declare function useTestMail(): TestMail;

package/dist/web/use-test-mail.js

@@ -0,0 +1,27 @@
+// @runtime client
+import { TemplateResolverHandlers } from "@cosmicdrift/kumiko-bundled-features/template-resolver/web";
+import { dispatcherErrorText, useMutation, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { useState } from "react";
+const TOO_MANY_REQUESTS = 429;
+// The recipient is always the caller; the server never returns the address.
+export function useTestMail() {
+    const t = useTranslation();
+    const sendTest = useMutation(TemplateResolverHandlers.sendTest);
+    const [state, setState] = useState({ kind: "idle" });
+    const send = async (payload) => {
+        setState({ kind: "idle" });
+        const result = await sendTest.mutate(payload);
+        if (result.isSuccess) {
+            setState({ kind: "sent", subject: result.data.subject });
+        }
+        else {
+            setState({
+                kind: "error",
+                text: result.error.httpStatus === TOO_MANY_REQUESTS
+                    ? t("documentDesigner.mail.testMail.rateLimited")
+                    : dispatcherErrorText(result.error, t),
+            });
+        }
+    };
+    return { state, pending: sendTest.pending, send };
+}

package/dist/web/used-by-label.d.ts

@@ -0,0 +1,9 @@
+import type { OverviewRowView, OverviewUsageView } from "./overview-row.js";
+type Translate = (key: string, params?: Readonly<Record<string, unknown>>) => string;
+export declare function usageParts(t: Translate, usage: OverviewUsageView): {
+    readonly feature: string;
+    readonly notification: string;
+};
+export declare function usageLabel(t: Translate, usage: OverviewUsageView): string;
+export declare function usedByLabel(t: Translate, row: OverviewRowView): string;
+export {};

package/dist/web/used-by-label.js

@@ -0,0 +1,32 @@
+// @runtime client
+import { DEFAULT_LAYOUT_SLUG } from "../constants.js";
+// t() returns the key itself when no translation exists.
+function translateOrRaw(t, key, raw) {
+    const translated = t(key);
+    return translated === key ? raw : translated;
+}
+export function usageParts(t, usage) {
+    return {
+        feature: translateOrRaw(t, `${usage.feature}:feature.label`, usage.feature),
+        notification: translateOrRaw(t, `${usage.feature}:notify.${usage.notification}.label`, usage.notification),
+    };
+}
+export function usageLabel(t, usage) {
+    const { feature, notification } = usageParts(t, usage);
+    return usage.feature === "" ? notification : `${feature} · ${notification}`;
+}
+export function usedByLabel(t, row) {
+    const emptyMark = "–";
+    if (row.kind === "mail-layout" || row.kind === "pdf-layout") {
+        if (row.slug === DEFAULT_LAYOUT_SLUG) {
+            return t(row.kind === "mail-layout"
+                ? "documentDesigner.usedBy.allMails"
+                : "documentDesigner.usedBy.allPdfs");
+        }
+        return row.usedByCount === 0
+            ? emptyMark
+            : t("documentDesigner.usedBy.templates", { count: row.usedByCount });
+    }
+    const first = row.usedBy[0];
+    return first === undefined ? emptyMark : usageLabel(t, first);
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@cosmicdrift/kumiko-document-designer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.364.0",
+  "description": "Document designer for Kumiko: template overview, layout editor (mail layout, PDF letterhead) and the PDF template editor.",
+  "license": "BUSL-1.1",
+  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
+  "type": "module",
+  "kumiko": {
+    "runtime": "runtime"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./web": {
+      "types": "./dist/web/index.d.ts",
+      "default": "./dist/web/index.js"
+    }
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "0.364.0",
+    "@cosmicdrift/kumiko-framework": "0.364.0",
+    "@cosmicdrift/kumiko-headless": "0.364.0",
+    "@cosmicdrift/kumiko-renderer": "0.364.0",
+    "@cosmicdrift/kumiko-renderer-puppeteer-client": "0.364.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.364.0",
+    "@cosmicdrift/kumiko-types": "0.364.0",
+    "pdfjs-dist": "6.3.289",
+    "react": "^19.2.6"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CosmicDriftGameStudio/kumiko-framework.git",
+    "directory": "packages/document-designer"
+  },
+  "homepage": "https://kumiko.rocks",
+  "bugs": {
+    "url": "https://github.com/CosmicDriftGameStudio/kumiko-framework/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "./web": {
+        "types": "./dist/web/index.d.ts",
+        "default": "./dist/web/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src/changes.json",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/changes.json

@@ -0,0 +1,44 @@
+[
+  {
+    "version": "0.364.0",
+    "type": "improvement",
+    "title": "Editors and overview show an open draft beside the active version",
+    "detail": "The editor header shows the served version (Active vN) next to the open draft (Draft vM), fed by the active field of find-by-id and layout-source; the template overview shows the draftVersion badge under the status of an active row."
+  },
+  {
+    "version": "0.364.0",
+    "type": "improvement",
+    "title": "Document designer editors follow the approved board",
+    "detail": "Mail-layout templates accept appearance meta (width, font, outer background, accent line, button style) that the mail renderer applies, and the layout-source query returns it. The layout editor uses the shared editor shell with one paper and one shared toolbar (`DocumentContentEditor` gains `toolbarHost`). Mail and PDF editors share frame, info bar, rails and footer.\nThe unused `sender` key of mail template meta is gone from the editor; stored rows that still carry it are read without it, so they stay editable.\nInvalid template meta now reports per-field messages (`templateResolver.errors.template.meta.<field>.required|invalid`) instead of the parser text; the editors show them at the field. The `tenant-overrides` query additionally returns one row per customising tenant (name, status, version, changed at/by) and, with `diffTenantId`, the diff to the system version. A language without a version shows an empty state in the mail editor instead of a disabled editor.\nThe `compileDocumentBody` option `resourceImageMaxWidthPx` caps resource images in mails (180 px). The `send-test` command takes `prefixSubject` (default true) to skip the `[TEST]` subject prefix, the template preview returns `mailLayout` (slug, scope, version of the layout used), and `RenderedMail` carries the layout ref."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "PDF editor keeps unset margins unset, frees old PDF previews, and shows reset and diff errors",
+    "detail": "Setting one margin no longer stores the other three as 15 mm, so the layout's header and footer margins still apply to them. The PDF preview no longer re-renders pages or stacks text layers on re-render and destroys the previous document. A failed reset to the system version shows an error banner in the PDF and mail editors, and a failing diff query shows an error state with retry instead of loading forever. The canvas reserves the footer margin like the renderer. Page formats, orientations and default margins now come from template-resolver (new exports PDF_ORIENTATIONS, PDF_DEFAULT_MARGIN_MM, PDF_HEADER_MARGIN_MM, PDF_FOOTER_MARGIN_MM, PdfOrientation)."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Layout editor shows the real number of mails or PDFs using a layout",
+    "detail": "The editor asks the overview for the users of one layout (kind and layoutSlug filter) and takes the count from total, so a tenant with more than 200 templates no longer sees a too low usage number."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Mail templates open in a mail editor with preview and test mail",
+    "detail": "The \"Edit\" row action of a mail template opens the new mail-editor screen: subject, preview text and content with placeholders from the notification, logo and file attachments, PDF-template attachments, layout and category, sandboxed preview (HTML or text, desktop or 375 px), test mail to the signed-in user and the audit-based version list. PreviewRecordPickerProvider is an optional slot for a \"pick a record\" action in the preview."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Template overview, layout editor and an options object for documentDesignerClient",
+    "detail": "The package gains the server feature createDocumentDesignerFeature with the templates and platform-templates overviews and the layout-editor screen. documentDesignerClient now takes an options object instead of a screen id, and appLocales sets the languages column of the overview. The feature declares the pdf-template-editor screen (PDF_TEMPLATE_EDITOR_SCREEN_ID) and PDF rows open the PDF editor."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "New package with the PDF template editor screen",
+    "detail": "\"@cosmicdrift/kumiko-document-designer/web\" exports documentDesignerClient(screenId), PdfTemplateEditorScreen, PdfTemplateEditor and documentDesignerTranslations. The screen takes the template from the URL (?slug=...&locale=...), edits the system template for a SystemAdmin and a tenant customisation for everyone else, and previews the printed PDF with pdf.js. template-resolver/web additionally exports DocumentEditorHandle, TemplateResolverQueries, TemplateResolverHandlers and TemplateResolverErrors."
+  }
+]