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

package/dist/web/types.d.ts

@@ -0,0 +1,103 @@
+import type { FieldIssue } from "@cosmicdrift/kumiko-headless";
+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;
+};
+export type VariableType = "text" | "link" | "money" | "date" | "list";
+export type VariableInfo = {
+    readonly type: VariableType;
+    readonly label?: string;
+    readonly required?: boolean;
+};
+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 TenantOverrides = {
+    readonly activeOverrides: number;
+    readonly draftOverrides: number;
+    readonly totalTenants: number | 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";
+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,15 @@
+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;
+    readonly sender: unknown;
+}): 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, args.sender),
+            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-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.363.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.363.0",
+    "@cosmicdrift/kumiko-framework": "0.363.0",
+    "@cosmicdrift/kumiko-headless": "0.363.0",
+    "@cosmicdrift/kumiko-renderer": "0.363.0",
+    "@cosmicdrift/kumiko-renderer-puppeteer-client": "0.363.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.363.0",
+    "@cosmicdrift/kumiko-types": "0.363.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,20 @@
+[
+  {
+    "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."
+  }
+]