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

package/LICENSE

@@ -0,0 +1,57 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Marc Frost
+
+Licensed Work:        @cosmicdrift/kumiko-document-designer
+                      The Licensed Work is © 2026 Marc Frost.
+
+Additional Use Grant: 
+You may use the Licensed Work in production for any purpose, including 
+commercially, EXCEPT for the Restricted Use. 
+
+"Restricted Use" is defined as using the Licensed Work to provide a platform 
+or service to third parties that allows them to host, deploy, or run their 
+own applications built with the Licensed Work. This includes, but is not 
+limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
+platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
+managed offering of the Licensed Work.
+
+This restriction does not apply to the Licensor, any entity controlled by, 
+controlling, or under common control with the Licensor ("Affiliates"), or 
+contractors acting on their behalf. The Licensor remains free to use the 
+Licensed Work for any purpose, including for the operation of kumiko.rocks.
+
+Change Date:          2030-05-05
+Change License:       Apache License, Version 2.0
+
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative works, 
+redistribute, and make non-production use of the Licensed Work. The Licensor may 
+make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly 
+available distribution of the Licensed Work under this License, whichever comes 
+first, this License will convert to the Change License.
+
+This Business Source License governs use of the Licensed Work in all cases, except 
+as to any use that is explicitly granted in the Additional Use Grant above or 
+under the Change License after the Change Date.
+
+If your use of the Licensed Work does not comply with the requirements of this 
+License, you must cease use of the Licensed Work immediately.
+
+All copies of the Licensed Work, and all derivative works thereof, must include 
+this License.
+
+This License does not grant you any right, title, or interest in any trademark, 
+logo, or branding of the Licensor, except as required to comply with this License.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
+“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
+WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
+TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
+ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @cosmicdrift/kumiko-document-designer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Document designer for Kumiko: the template overview, the layout editor for the mail layout and the PDF letterhead, and the PDF template editor.
+
+```ts
+import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { createDocumentDesignerFeature } from "@cosmicdrift/kumiko-document-designer";
+import { documentDesignerClient } from "@cosmicdrift/kumiko-document-designer/web";
+
+// server feature list
+createTemplateResolverFeature();
+createDocumentDesignerFeature();
+
+createKumikoApp({
+  clientFeatures: [
+    documentDesignerClient({ appLocales: ["de", "en"] }),
+  ],
+});
+```
+
+## Overview and layout editor
+
+Mount `createDocumentDesignerFeature()` after `template-resolver` (and `managed-pages` if the branding rail should link to the branding screen).
+
+- Screens: `templates` (TenantAdmin, SystemAdmin), `platform-templates` (SystemAdmin, adds the "customised by" column), `layout-editor` (opened from the "Edit" row action of a layout), `mail-editor` (opened from the "Edit" row action of a mail template; subject, content, resources, preview and test mail).
+- Navs: `document-designer:nav:templates` and `document-designer:nav:platform-templates`. `createAdminShellFeature({ includeDocumentDesigner: true })` lists them in the admin workspaces.
+- `TEMPLATE_EDITOR_SCREENS` maps a template kind to the screen that edits it; adding a kind there adds the "Edit" row action.
+- `PreviewRecordPickerProvider` (web export) adds a "pick a record" action to the mail preview; without it the action is hidden. Picked values are shown only, the preview endpoint takes no overrides.
+- The MJML tab of the layout editor is shown to SystemAdmin only and only when the system layout is MJML.
+
+## PDF template editor
+
+The feature declares the `pdf-template-editor` screen (`PDF_TEMPLATE_EDITOR_SCREEN_ID`) and `documentDesignerClient()` registers its component; the "Edit" row action of PDF rows opens it. The screen reads the template from the URL: `?slug=invoice&locale=de`.
+`PdfTemplateEditor` (props `slug`, `locale`, `onLocaleChange`) can also be mounted directly.
+
+Requirements: the `template-resolver` and `renderer-puppeteer-client` features on the server.
+A SystemAdmin (via `UserRolesProvider`) edits the system template, everyone else a tenant customisation.
+PDF preview uses `pdfjs-dist` in the main thread (no worker or CDN requests).

package/dist/constants.d.ts

@@ -0,0 +1,24 @@
+export declare const DOCUMENT_DESIGNER_FEATURE: "document-designer";
+export declare const TEMPLATES_SCREEN_ID: "templates";
+export declare const PLATFORM_TEMPLATES_SCREEN_ID: "platform-templates";
+export declare const LAYOUT_EDITOR_SCREEN_ID: "layout-editor";
+export declare const PDF_TEMPLATE_EDITOR_SCREEN_ID: "pdf-template-editor";
+export declare const MAIL_EDITOR_SCREEN_ID: "mail-editor";
+export declare const TEMPLATES_NAV_ID: "templates";
+export declare const PLATFORM_TEMPLATES_NAV_ID: "platform-templates";
+export declare const BRANDING_SCREEN_QN: "managed-pages:screen:branding-settings";
+export declare const BRANDING_QUERY_QN: "managed-pages:query:branding";
+export declare const DEFAULT_LAYOUT_SLUG: "default";
+export type TemplateEditorKind = "mail" | "document-pdf" | "mail-layout" | "pdf-layout";
+export declare const TEMPLATE_EDITOR_SCREENS: Partial<Record<TemplateEditorKind, string>>;
+export declare const DocumentDesignerCells: {
+    readonly title: "document-designer-title-cell";
+    readonly kind: "document-designer-kind-cell";
+    readonly origin: "document-designer-origin-cell";
+    readonly locales: "document-designer-locales-cell";
+    readonly status: "document-designer-status-cell";
+    readonly usedBy: "document-designer-used-by-cell";
+    readonly modifiedAt: "document-designer-modified-cell";
+    readonly overriddenBy: "document-designer-overridden-by-cell";
+};
+export declare const DEFAULT_TEMPLATE_LOCALES: readonly string[];

package/dist/constants.js

@@ -0,0 +1,33 @@
+// @runtime client
+// Names shared by the server feature and the client plugin. Plain data, no imports.
+export const DOCUMENT_DESIGNER_FEATURE = "document-designer";
+export const TEMPLATES_SCREEN_ID = "templates";
+export const PLATFORM_TEMPLATES_SCREEN_ID = "platform-templates";
+export const LAYOUT_EDITOR_SCREEN_ID = "layout-editor";
+export const PDF_TEMPLATE_EDITOR_SCREEN_ID = "pdf-template-editor";
+export const MAIL_EDITOR_SCREEN_ID = "mail-editor";
+export const TEMPLATES_NAV_ID = "templates";
+export const PLATFORM_TEMPLATES_NAV_ID = "platform-templates";
+export const BRANDING_SCREEN_QN = "managed-pages:screen:branding-settings";
+export const BRANDING_QUERY_QN = "managed-pages:query:branding";
+export const DEFAULT_LAYOUT_SLUG = "default";
+// Short screen id per template kind. A kind without an entry gets no "Edit" row action.
+// The mail editor adds `mail` here and declares its screen in this feature, because the
+// boot validator only accepts navigate targets in the same feature.
+export const TEMPLATE_EDITOR_SCREENS = {
+    "document-pdf": PDF_TEMPLATE_EDITOR_SCREEN_ID,
+    mail: MAIL_EDITOR_SCREEN_ID,
+    "mail-layout": LAYOUT_EDITOR_SCREEN_ID,
+    "pdf-layout": LAYOUT_EDITOR_SCREEN_ID,
+};
+export const DocumentDesignerCells = {
+    title: "document-designer-title-cell",
+    kind: "document-designer-kind-cell",
+    origin: "document-designer-origin-cell",
+    locales: "document-designer-locales-cell",
+    status: "document-designer-status-cell",
+    usedBy: "document-designer-used-by-cell",
+    modifiedAt: "document-designer-modified-cell",
+    overriddenBy: "document-designer-overridden-by-cell",
+};
+export const DEFAULT_TEMPLATE_LOCALES = ["de", "en"];

package/dist/feature.d.ts

@@ -0,0 +1,2 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export declare function createDocumentDesignerFeature(): FeatureDefinition;

package/dist/feature.js

@@ -0,0 +1,85 @@
+import { access, defineFeature, i18nKey, } from "@cosmicdrift/kumiko-framework/engine";
+import { DOCUMENT_DESIGNER_FEATURE, LAYOUT_EDITOR_SCREEN_ID, MAIL_EDITOR_SCREEN_ID, PDF_TEMPLATE_EDITOR_SCREEN_ID, PLATFORM_TEMPLATES_NAV_ID, PLATFORM_TEMPLATES_SCREEN_ID, TEMPLATES_NAV_ID, TEMPLATES_SCREEN_ID, } from "./constants.js";
+import { DOCUMENT_DESIGNER_I18N } from "./i18n.js";
+import { TEMPLATE_FACETS, templateColumns, templateRowActions } from "./list-definition.js";
+const OVERVIEW_QUERY = "template-resolver:query:overview";
+const TENANT_ROLES = ["TenantAdmin", "SystemAdmin"];
+export function createDocumentDesignerFeature() {
+    return defineFeature(DOCUMENT_DESIGNER_FEATURE, (r) => {
+        r.describe("Template overview and layout editor: lists the mail, PDF and layout templates of a tenant (platform admins see the system templates and how many tenants customised each) and edits the mail layout and the PDF letterhead in the browser. Mount after template-resolver and, for the branding rail, managed-pages. Client: `documentDesignerClient()`; admin-shell lists the navs with `includeDocumentDesigner`.");
+        r.uiHints({
+            displayLabel: "Documents · Template Designer",
+            category: "content",
+            recommended: false,
+        });
+        r.requires("template-resolver");
+        r.translations({ keys: DOCUMENT_DESIGNER_I18N });
+        r.screen({
+            id: TEMPLATES_SCREEN_ID,
+            type: "projectionList",
+            query: OVERVIEW_QUERY,
+            columns: templateColumns({ platform: false }),
+            facets: [...TEMPLATE_FACETS],
+            rowActions: templateRowActions(),
+            searchable: true,
+            searchPlaceholder: i18nKey("documentDesigner.search"),
+            pagination: "pages",
+            defaultSort: { field: "modifiedAt", dir: "desc" },
+            access: { roles: access.roles(...TENANT_ROLES) },
+        });
+        r.nav({
+            id: TEMPLATES_NAV_ID,
+            label: "document-designer:nav.templates",
+            icon: "file",
+            screen: `${DOCUMENT_DESIGNER_FEATURE}:screen:${TEMPLATES_SCREEN_ID}`,
+            access: { roles: access.roles(...TENANT_ROLES) },
+            order: 15,
+        });
+        r.screen({
+            id: PLATFORM_TEMPLATES_SCREEN_ID,
+            type: "projectionList",
+            query: OVERVIEW_QUERY,
+            columns: templateColumns({ platform: true }),
+            facets: [...TEMPLATE_FACETS],
+            rowActions: templateRowActions(),
+            searchable: true,
+            searchPlaceholder: i18nKey("documentDesigner.search"),
+            pagination: "pages",
+            defaultSort: { field: "modifiedAt", dir: "desc" },
+            access: { roles: access.systemAdmin },
+        });
+        r.nav({
+            id: PLATFORM_TEMPLATES_NAV_ID,
+            label: "document-designer:nav.platformTemplates",
+            icon: "file",
+            screen: `${DOCUMENT_DESIGNER_FEATURE}:screen:${PLATFORM_TEMPLATES_SCREEN_ID}`,
+            access: { roles: access.systemAdmin },
+            order: 15,
+        });
+        r.screen({
+            id: LAYOUT_EDITOR_SCREEN_ID,
+            type: "custom",
+            renderer: { react: { __component: LAYOUT_EDITOR_SCREEN_ID } },
+            description: "documentDesigner.screen.layoutEditor.description",
+            dormant: true,
+            access: { roles: access.roles(...TENANT_ROLES) },
+        });
+        r.screen({
+            id: PDF_TEMPLATE_EDITOR_SCREEN_ID,
+            type: "custom",
+            renderer: { react: { __component: PDF_TEMPLATE_EDITOR_SCREEN_ID } },
+            description: "Editor for one PDF template: edit the body, print a preview through the print service, review tenant customisations and export the template as a bundle.",
+            dormant: true,
+            access: { roles: access.roles(...TENANT_ROLES) },
+        });
+        // kumiko-lint-ignore app-feature-structure Board-2/3 mail editor (placeholder rail, chip editors, live preview, test mail) has no declarative screen type
+        r.screen({
+            id: MAIL_EDITOR_SCREEN_ID,
+            type: "custom",
+            renderer: { react: { __component: MAIL_EDITOR_SCREEN_ID } },
+            description: "documentDesigner.screen.mailEditor.description",
+            dormant: true,
+            access: { roles: access.roles(...TENANT_ROLES) },
+        });
+    });
+}

package/dist/i18n.d.ts

@@ -0,0 +1,6 @@
+type Localized = {
+    readonly en: string;
+    readonly de: string;
+};
+export declare const DOCUMENT_DESIGNER_I18N: Readonly<Record<string, Localized>>;
+export {};