@cosmicdrift/kumiko-samples 0.377.0 → 0.378.0

package/samples/apps/ui-walkthrough/src/app/template-seed-data.ts

@@ -535,6 +535,26 @@ export const SYSTEM_TENANCY_CERTIFICATE: SeedTemplate = {
   },
 };
 
+export const SYSTEM_PROPERTY_EXPOSE: SeedTemplate = {
+  slug: "rental:property-expose",
+  kind: "document-pdf",
+  locale: "de",
+  title: "Exposé",
+  content: [
+    `<h1>Exposé ${v("propertyAddress")}</h1>`,
+    `<p>${v("propertySummary")}</p>`,
+    "<h2>Objektfotos</h2>",
+    '<div data-images="photos"></div>',
+  ].join(""),
+  meta: { layoutSlug: "default", pageFormat: "A4", fileName: "Expose.pdf" },
+  variableSchema: {
+    propertyAddress: { type: "text", required: true },
+    propertySummary: { type: "text", required: true },
+    // The app passes the FileRef ids of the property photos when it renders the PDF.
+    photos: { type: "images", label: "Objektfotos" },
+  },
+};
+
 // Two other tenants customise the invoice for the "Anpassungen der Mandanten" drawer: one
 // published copy with a second save, one draft.
 export type TenantInvoiceOverride = {

package/samples/apps/ui-walkthrough/src/features/rental/feature.ts

@@ -1,12 +1,18 @@
 import type { EventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
-import { defineFeature, i18nKey } from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature, defineWriteHandler, i18nKey } from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  renderPdfBeforeTransaction,
+  storeRenderedPdf,
+} from "@cosmicdrift/kumiko-renderer-puppeteer-client";
 import { z } from "zod";
 import { openToAllSignedIn, toKeyFirst } from "../translations";
 import { leaseEntity, leasePartyEntity, leasePositionEntity } from "./entities";
 import { rentalTranslations } from "./i18n";
+import { receiveInvoicePayloadSchema } from "./invoice-receive";
 import {
   dayBefore,
+  fileRefIdsPayloadSchema,
   formatGermanDate,
   formatGermanMoney,
   germanStatusLabel,
@@ -18,6 +24,7 @@ import {
   positionExecutor,
   positionListRowSchema,
   positionRowSchema,
+  propertyExposePayloadSchema,
   type RecordedPositionItem,
   recordPositionsPayloadSchema,
   rentAdjustPayloadSchema,
@@ -32,8 +39,10 @@ import {
   leaseListScreen,
   leaseListShortScreen,
   leaseSuccessionListScreen,
+  leaseUnterlagenScreen,
   partyEditScreen,
   positionEditScreen,
+  receiveInvoiceScreen,
   recordPositionsScreen,
   rentalDashboardScreen,
 } from "./screens";
@@ -95,6 +104,17 @@ export const rentalFeature = defineFeature("rental", (r) => {
   });
   r.crud("leaseParty", leasePartyEntity, { write: open, read: open });
 
+  r.queryHandler({
+    name: "lease:unterlagen",
+    schema: fileRefIdsPayloadSchema,
+    handler: async (query) => ({
+      id: "unterlagen",
+      titel: "Unterlagen",
+      unterlagen: query.payload.id,
+    }),
+    ...open,
+  });
+
   r.queryHandler({
     name: "lease:akte",
     schema: idPayloadSchema,
@@ -217,6 +237,28 @@ export const rentalFeature = defineFeature("rental", (r) => {
     ...open,
   });
 
+  r.writeHandler({
+    name: "invoice:receive",
+    schema: receiveInvoicePayloadSchema,
+    handler: async (event) => ({ isSuccess: true, data: event.payload }),
+    ...open,
+  });
+
+  r.writeHandler(
+    defineWriteHandler({
+      name: "generate-property-expose",
+      schema: propertyExposePayloadSchema,
+      access: { roles: ["TenantAdmin"] },
+      beforeTransaction: async (event, ctx) =>
+        renderPdfBeforeTransaction(ctx, {
+          slug: "rental:property-expose",
+          locale: "de",
+          variables: event.payload,
+        }),
+      handler: async (event, ctx) => storeRenderedPdf(ctx, event.prepared),
+    }),
+  );
+
   r.writeHandler({
     name: "rent:adjust",
     schema: rentAdjustPayloadSchema,
@@ -270,6 +312,14 @@ export const rentalFeature = defineFeature("rental", (r) => {
   r.screen(rentalDashboardScreen);
   r.screen(adjustRentScreen);
   r.screen(recordPositionsScreen);
+  r.screen(receiveInvoiceScreen);
+  r.screen(leaseUnterlagenScreen);
+  r.screen({
+    id: "upload-standard-layout",
+    type: "custom",
+    renderer: { react: { __component: "upload-standard-layout" } },
+    description: "Receipt upload on the standard form screen layout.",
+  });
 
   r.nav({
     id: "contracts",
@@ -290,4 +340,18 @@ export const rentalFeature = defineFeature("rental", (r) => {
     screen: "rental:screen:rental-dashboard",
     order: 20,
   });
+  r.nav({
+    id: "receive-invoice",
+    label: i18nKey("rental.nav.receiveInvoice"),
+    parent: "rental:nav:contracts",
+    screen: "rental:screen:receive-invoice",
+    order: 40,
+  });
+  r.nav({
+    id: "upload-standard-layout",
+    label: i18nKey("rental.nav.upload"),
+    parent: "rental:nav:contracts",
+    screen: "rental:screen:upload-standard-layout",
+    order: 30,
+  });
 });

package/samples/apps/ui-walkthrough/src/features/rental/i18n.ts

@@ -4,6 +4,23 @@ export const rentalTranslations: TranslationsByLocale = {
   de: {
     "rental.nav.contracts": "Verträge",
     "rental.nav.leases": "Mietverträge",
+    "screen:lease-unterlagen.title": "Unterlagen",
+    "rental.unterlagen.label": "Dateien",
+    "rental.unterlagen.section": "Mietvertragsunterlagen",
+    "rental.unterlagen.sectionDescription":
+      "Hochgeladene Rechnungen und Belege zum Download und zur Ansicht.",
+    "rental.nav.upload": "Belege hochladen",
+    "screen:upload-standard-layout.title": "Belege hochladen",
+    "rental.upload.description":
+      "Laden Sie Rechnungen und Nebenkostenbelege zum Mietvertrag hoch. Danach gehen sie zur Prüfung.",
+    "rental.upload.zoneTitle": "Belege auswählen",
+    "rental.upload.zoneDescription": "PDF oder Foto, mehrere Dateien auf einmal sind möglich.",
+    "rental.upload.dropTitle": "Rechnungen und Belege hier ablegen",
+    "rental.upload.dropHint": "PDF, JPG oder PNG",
+    "rental.upload.resultTitle": "Hochgeladene Belege",
+    "rental.upload.resultDescription": "Diese Dateien gehen mit der Prüfung an die Buchhaltung.",
+    "rental.upload.empty": "Noch keine Belege hochgeladen.",
+    "rental.upload.toReview": "Zur Prüfung",
 
     "screen:lease-list.title": "Mietverträge",
     "screen:lease-list-short.title": "Mietverträge (gekündigt)",
@@ -96,6 +113,24 @@ export const rentalTranslations: TranslationsByLocale = {
     "screen:record-positions.title": "Positionen erfassen",
     "rental.section.items": "Positionen",
     "rental.action.recordPositions": "Positionen speichern",
+    "rental.nav.receiveInvoice": "Eingangsrechnung",
+    "screen:receive-invoice.title": "Eingangsrechnung erfassen",
+    "rental.section.invoiceLines": "Rechnungspositionen",
+    "rental.section.invoiceTotals": "Summen",
+    "rental.section.invoiceTotalsHint":
+      "Mit Positionen sind die Summen berechnet. Ohne Positionen tragen Sie Netto und USt.-Satz ein.",
+    "rental.action.receiveInvoice": "Rechnung erfassen",
+    "rental:entity:__action-form__:field:supplier": "Lieferant",
+    "rental:entity:__action-form__:field:invoiceNumber": "Rechnungsnummer",
+    "rental:entity:__action-form__:field:lines": "Positionen",
+    "rental:entity:__action-form__:field:lines:cell:description": "Leistung",
+    "rental:entity:__action-form__:field:lines:cell:amount": "Netto",
+    "rental:entity:__action-form__:field:lines:cell:vatRate": "USt. in %",
+    "rental:entity:__action-form__:field:lines:cell:vatAmount": "USt.",
+    "rental:entity:__action-form__:field:netTotal": "Netto gesamt",
+    "rental:entity:__action-form__:field:vatRate": "USt.-Satz in %",
+    "rental:entity:__action-form__:field:vatTotal": "USt. gesamt",
+    "rental:entity:__action-form__:field:grossTotal": "Brutto gesamt",
     "rental:entity:__action-form__:field:lease": "Mietvertrag",
     "rental:entity:__action-form__:field:items": "Positionen",
     "rental:entity:__action-form__:field:zahlungsweise": "Zahlungsweise",
@@ -121,6 +156,23 @@ export const rentalTranslations: TranslationsByLocale = {
   en: {
     "rental.nav.contracts": "Contracts",
     "rental.nav.leases": "Leases",
+    "screen:lease-unterlagen.title": "Documents",
+    "rental.unterlagen.label": "Files",
+    "rental.unterlagen.section": "Lease documents",
+    "rental.unterlagen.sectionDescription":
+      "Uploaded invoices and receipts to download or preview.",
+    "rental.nav.upload": "Upload receipts",
+    "screen:upload-standard-layout.title": "Upload receipts",
+    "rental.upload.description":
+      "Upload invoices and service charge receipts for the lease. They then go to review.",
+    "rental.upload.zoneTitle": "Choose receipts",
+    "rental.upload.zoneDescription": "PDF or photo, several files at once are fine.",
+    "rental.upload.dropTitle": "Drop invoices and receipts here",
+    "rental.upload.dropHint": "PDF, JPG or PNG",
+    "rental.upload.resultTitle": "Uploaded receipts",
+    "rental.upload.resultDescription": "These files go to accounting with the review.",
+    "rental.upload.empty": "No receipts uploaded yet.",
+    "rental.upload.toReview": "To review",
 
     "screen:lease-list.title": "Leases",
     "screen:lease-list-short.title": "Leases (terminated)",
@@ -210,6 +262,24 @@ export const rentalTranslations: TranslationsByLocale = {
     "screen:record-positions.title": "Record positions",
     "rental.section.items": "Positions",
     "rental.action.recordPositions": "Save positions",
+    "rental.nav.receiveInvoice": "Incoming invoice",
+    "screen:receive-invoice.title": "Record incoming invoice",
+    "rental.section.invoiceLines": "Invoice lines",
+    "rental.section.invoiceTotals": "Totals",
+    "rental.section.invoiceTotalsHint":
+      "With lines the totals are computed. Without lines, enter the net amount and the VAT rate.",
+    "rental.action.receiveInvoice": "Record invoice",
+    "rental:entity:__action-form__:field:supplier": "Supplier",
+    "rental:entity:__action-form__:field:invoiceNumber": "Invoice number",
+    "rental:entity:__action-form__:field:lines": "Lines",
+    "rental:entity:__action-form__:field:lines:cell:description": "Service",
+    "rental:entity:__action-form__:field:lines:cell:amount": "Net",
+    "rental:entity:__action-form__:field:lines:cell:vatRate": "VAT in %",
+    "rental:entity:__action-form__:field:lines:cell:vatAmount": "VAT",
+    "rental:entity:__action-form__:field:netTotal": "Net total",
+    "rental:entity:__action-form__:field:vatRate": "VAT rate in %",
+    "rental:entity:__action-form__:field:vatTotal": "VAT total",
+    "rental:entity:__action-form__:field:grossTotal": "Gross total",
     "rental:entity:__action-form__:field:lease": "Lease",
     "rental:entity:__action-form__:field:items": "Positions",
     "rental:entity:__action-form__:field:zahlungsweise": "Payment method",

package/samples/apps/ui-walkthrough/src/features/rental/invoice-receive.ts

@@ -0,0 +1,20 @@
+import { fieldToZod, withFormDerivations } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { receiveInvoiceLines, receiveInvoiceScreen } from "./screens";
+
+const moneyPayload = z.object({ amount: z.number(), currency: z.string().min(1) });
+
+// Totals are recomputed from the lines before validation, so a client-sent
+// total never reaches the handler.
+export const receiveInvoicePayloadSchema = withFormDerivations(
+  z.object({
+    supplier: z.string().min(1),
+    invoiceNumber: z.string().min(1),
+    lines: fieldToZod(receiveInvoiceLines, ["EUR"]),
+    netTotal: moneyPayload,
+    vatRate: z.number().optional(),
+    vatTotal: moneyPayload,
+    grossTotal: moneyPayload,
+  }),
+  receiveInvoiceScreen,
+);

package/samples/apps/ui-walkthrough/src/features/rental/lease-support.ts

@@ -12,6 +12,21 @@ export const { executor: partyExecutor } = createEntityExecutor("leaseParty", le
 
 export const idPayloadSchema = z.object({ id: z.uuid() });
 
+// Walkthrough shortcut, not the pattern: a real handler reads the photo ids from the stored record, never from the client.
+export const propertyExposePayloadSchema = z.object({
+  propertyAddress: z.string().min(1),
+  propertySummary: z.string().min(1),
+  photos: z.array(z.uuid()).max(10),
+});
+
+// Walkthrough shortcut, not the pattern: real screens resolve FileRefs from the record, never from route-supplied ids.
+export const fileRefIdsPayloadSchema = z.object({
+  id: z
+    .string()
+    .transform((raw) => raw.split(","))
+    .pipe(z.array(z.uuid()).min(1).max(10)),
+});
+
 export const rentAdjustPayloadSchema = z.object({
   positionId: z.uuid(),
   wirksamAb: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),

package/samples/apps/ui-walkthrough/src/features/rental/qualified-names.ts

@@ -1,5 +1,6 @@
 export const RENTAL_QUERIES = {
   leaseAkte: "rental:query:lease:akte",
+  leaseUnterlagen: "rental:query:lease:unterlagen",
   partyList: "rental:query:lease-party:list",
   positionList: "rental:query:lease:positions",
   kennzahlen: "rental:query:lease:kennzahlen",
@@ -9,4 +10,5 @@ export const RENTAL_WRITES = {
   leaseTerminate: "rental:write:lease:terminate",
   rentAdjust: "rental:write:rent:adjust",
   positionsRecord: "rental:write:lease:record-positions",
+  invoiceReceive: "rental:write:invoice:receive",
 } as const;

package/samples/apps/ui-walkthrough/src/features/rental/screens.ts

@@ -1,5 +1,6 @@
 import {
   createDateField,
+  createDecimalField,
   createEmbeddedListField,
   createSelectField,
   createTextField,
@@ -462,6 +463,64 @@ export const recordPositionsScreen: ActionFormScreenDefinition = {
   access: OPEN_ACCESS,
 };
 
+const EUR = { kind: "literal", code: "EUR" } as const;
+
+export const receiveInvoiceLines = createEmbeddedListField(
+  {
+    description: { type: "text", required: true },
+    amount: { type: "money", required: true },
+    vatRate: { type: "decimal", scale: 2, required: true },
+    vatAmount: { type: "money" },
+  },
+  {
+    derived: { vatAmount: { op: "percent", from: ["amount", "vatRate"] } },
+    totals: ["amount", "vatAmount"],
+  },
+);
+
+export const receiveInvoiceScreen: ActionFormScreenDefinition = {
+  id: "receive-invoice",
+  type: "actionForm",
+  handler: RENTAL_WRITES.invoiceReceive,
+  fields: {
+    supplier: createTextField({ personal: "tenant", find: "none", required: true }),
+    invoiceNumber: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+    }),
+    lines: receiveInvoiceLines,
+    netTotal: { type: "money", currency: EUR },
+    vatRate: createDecimalField({ precision: 5, scale: 2 }),
+    vatTotal: { type: "money", currency: EUR },
+    grossTotal: { type: "money", currency: EUR },
+  },
+  derive: {
+    netTotal: { op: "listSum", list: "lines", cell: "amount" },
+    vatTotal: {
+      op: "listSum",
+      list: "lines",
+      cell: "vatAmount",
+      whenEmpty: { op: "percent", from: ["netTotal", "vatRate"] },
+    },
+    grossTotal: { op: "sum", from: ["netTotal", "vatTotal"] },
+  },
+  layout: {
+    width: "full",
+    sections: [
+      { fields: ["supplier", "invoiceNumber"] },
+      { title: "rental.section.invoiceLines", columns: 1, fields: ["lines"] },
+      {
+        title: "rental.section.invoiceTotals",
+        description: "rental.section.invoiceTotalsHint",
+        fields: ["netTotal", "vatRate", "vatTotal", "grossTotal"],
+      },
+    ],
+  },
+  submitLabel: "rental.action.receiveInvoice",
+  access: OPEN_ACCESS,
+};
+
 // Fixtures for the UI-gap screenshots: a confirm-gated primary action that is
 // visible only while the lease is active (a terminated lease falls back to edit
 // as the main button), and a list that is empty because of its default filter.
@@ -518,3 +577,23 @@ export const leaseSuccessionListScreen: EntityListScreenDefinition = {
   rowActions: [openLeaseDetail],
   access: OPEN_ACCESS,
 };
+
+export const leaseUnterlagenScreen: ProjectionDetailScreenDefinition = {
+  id: "lease-unterlagen",
+  type: "projectionDetail",
+  dormant: true,
+  query: RENTAL_QUERIES.leaseUnterlagen,
+  recordTitleField: "titel",
+  fieldLabels: { unterlagen: "rental.unterlagen.label" },
+  layout: {
+    sections: [
+      {
+        title: "rental.unterlagen.section",
+        description: "rental.unterlagen.sectionDescription",
+        icon: "file",
+        fields: [{ field: "unterlagen", renderer: { format: "file" } }],
+      },
+    ],
+  },
+  access: OPEN_ACCESS,
+};

package/samples/apps/ui-walkthrough/src/features/rental/web/index.ts

@@ -1,10 +1,12 @@
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer/web";
 import { rentalTranslations } from "../i18n";
 import { LeaseHubHeader, LeaseHubHistory } from "./lease-hub-components";
+import { UploadStandardLayout } from "./upload-standard-layout";
 
 export const rentalClient: ClientFeatureDefinition = {
   name: "rental",
   translations: rentalTranslations,
+  components: { "upload-standard-layout": UploadStandardLayout },
   extensionSectionComponents: {
     LeaseHubHeader,
     LeaseHubHistory,

package/samples/apps/ui-walkthrough/src/features/rental/web/upload-standard-layout.tsx

@@ -0,0 +1,61 @@
+import { FormScreenLayout, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { UploadZone, uploadFileRef } from "@cosmicdrift/kumiko-renderer/web";
+import { type ReactNode, useState } from "react";
+
+type UploadedReceipt = { readonly id: string; readonly name: string };
+
+export function UploadStandardLayout(): ReactNode {
+  const t = useTranslation();
+  const { Section, Button, Text } = usePrimitives();
+  const [uploadedReceipts, setUploadedNames] = useState<readonly UploadedReceipt[]>([]);
+
+  async function uploadReceipt(file: File): Promise<void> {
+    await uploadFileRef(file);
+    setUploadedNames((receipts) => [...receipts, { id: crypto.randomUUID(), name: file.name }]);
+  }
+
+  return (
+    <FormScreenLayout
+      testId="upload-standard-layout"
+      description={t("rental.upload.description")}
+      actions={
+        uploadedReceipts.length > 0 ? (
+          <Button testId="upload-to-review">{t("rental.upload.toReview")}</Button>
+        ) : undefined
+      }
+    >
+      <Section
+        title={t("rental.upload.zoneTitle")}
+        icon="upload"
+        subtitle={t("rental.upload.zoneDescription")}
+        testId="upload-zone-section"
+      >
+        <UploadZone
+          testId="upload-zone"
+          title={t("rental.upload.dropTitle")}
+          hint={t("rental.upload.dropHint")}
+          accept={["application/pdf", "image/*"]}
+          onUpload={uploadReceipt}
+        />
+      </Section>
+      <Section
+        title={t("rental.upload.resultTitle")}
+        icon="file"
+        subtitle={t("rental.upload.resultDescription")}
+        testId="upload-result-section"
+      >
+        {uploadedReceipts.length === 0 ? (
+          <Text variant="muted">{t("rental.upload.empty")}</Text>
+        ) : (
+          <ul data-testid="upload-result-list" className="space-y-2">
+            {uploadedReceipts.map(({ id, name }) => (
+              <li key={id} className="text-sm">
+                {name}
+              </li>
+            ))}
+          </ul>
+        )}
+      </Section>
+    </FormScreenLayout>
+  );
+}

package/samples/apps/ui-walkthrough/src/features/tasks/i18n.ts

@@ -9,6 +9,10 @@ export const tasksTranslations: TranslationsByLocale = {
     "tasks.assistant.label": "Assistent",
     "tasks.assistant.description": "Der Assistent ist im Walkthrough nicht angebunden.",
     "tasks.assistant.close": "Schließen",
+    "tasks.help.label": "Hilfe",
+    "tasks.help.description": "Kurzhilfe zur aktuellen Seite.",
+    "tasks.help.body":
+      "Die Seite bleibt bedienbar: Sie rückt neben das Hilfefenster, statt darunter zu verschwinden.",
     "tasks.nav.group": "Allgemein",
     "tasks.nav.list": "Aufgaben",
     "tasks.nav.new": "Neue Aufgabe",
@@ -29,6 +33,10 @@ export const tasksTranslations: TranslationsByLocale = {
     "tasks.assistant.label": "Assistant",
     "tasks.assistant.description": "The assistant is not connected in the walkthrough.",
     "tasks.assistant.close": "Close",
+    "tasks.help.label": "Help",
+    "tasks.help.description": "Quick help for the current page.",
+    "tasks.help.body":
+      "The page stays usable: it moves next to the help panel instead of disappearing under it.",
     "tasks.nav.group": "General",
     "tasks.nav.list": "Tasks",
     "tasks.nav.new": "New task",

package/samples/apps/ui-walkthrough/src/run-config.ts

@@ -4,14 +4,20 @@
 // from here — migration and runtime cannot drift.
 
 import { createAuditFeature } from "@cosmicdrift/kumiko-bundled-features/audit";
+import { AuthMailNotificationTypes } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
 import {
   createChannelEmailFeature,
   createInMemoryTransport,
 } from "@cosmicdrift/kumiko-bundled-features/channel-email";
 import { createDeliveryFeature } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { createFilesFeature } from "@cosmicdrift/kumiko-bundled-features/files";
 import { createManagedPagesFeature } from "@cosmicdrift/kumiko-bundled-features/managed-pages";
 import { createRendererFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
-import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import {
+  createTemplateResolverFeature,
+  type TenantEditableTemplate,
+  templateEditAccess,
+} from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 import { createDocumentDesignerFeature } from "@cosmicdrift/kumiko-document-designer";
 import { localeDe } from "@cosmicdrift/kumiko-locale-de";
 import { localeEs } from "@cosmicdrift/kumiko-locale-es";
@@ -23,6 +29,27 @@ import { rentalFeature } from "./features/rental";
 import { taskFeature } from "./features/tasks";
 import { vehiclesFeature } from "./features/vehicles";
 
+// The walkthrough shows the tenant admin editing these templates; every other template stays with the platform.
+const TENANT_EDITABLE_TEMPLATES: readonly TenantEditableTemplate[] = [
+  ...[
+    "billing:notify:invoice-issued",
+    "billing:notify:invoice-corrected",
+    "billing:notify:payment-reminder",
+    "billing:notify:terms-changed",
+    AuthMailNotificationTypes.passwordReset,
+  ].map((slug) => ({ kind: "mail" as const, slug, access: { roles: ["TenantAdmin"] } })),
+  ...["billing:invoice", "rental:utility-statement"].map((slug) => ({
+    kind: "document-pdf" as const,
+    slug,
+    access: { roles: ["TenantAdmin"] },
+  })),
+  ...(["mail-layout", "pdf-layout"] as const).map((kind) => ({
+    kind,
+    slug: "default",
+    access: { roles: ["TenantAdmin"] },
+  })),
+];
+
 export const APP_FEATURES = [
   localeDe(),
   // Spanish mail copy: subscribers whose mails go out in Spanish land on Spanish unsubscribe pages.
@@ -31,11 +58,13 @@ export const APP_FEATURES = [
   rentalFeature,
   vehiclesFeature,
   billingFeature,
-  createTemplateResolverFeature(),
+  createTemplateResolverFeature({ tenantEditable: TENANT_EDITABLE_TEMPLATES }),
   // Only the branding rail of the layout editor needs managed-pages; the sample
   // serves no public pages, so no host resolves to a tenant.
   createManagedPagesFeature({ resolveApexTenant: () => null }),
-  createDocumentDesignerFeature(),
+  // The mail editor offers uploads only when the files feature is mounted.
+  createFilesFeature(),
+  createDocumentDesignerFeature({ access: templateEditAccess(TENANT_EDITABLE_TEMPLATES) }),
   // Mounted individually: composeRendererStack() would add a second template-resolver.
   createRendererFoundationFeature(),
   createRendererMailHtmlFeature({

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -795,7 +795,7 @@
     },
     {
       "name": "document-designer",
-      "description": "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`.",
+      "description": "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`. The tenant overview and the editors are for SystemAdmin only; the `access` option adds roles (normally `templateEditAccess(tenantEditable)` of the template-resolver mount), and the server still enforces per template which of them may save.",
       "toggleableDefault": null,
       "requires": [
         "template-resolver"
@@ -2602,7 +2602,7 @@
     },
     {
       "name": "template-resolver",
-      "description": "Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail`, `mail-layout`, `document-pdf`, `pdf-layout`, `ai-prompt`, `text-block`, `snippet`, `image-snapshot`).\n\nReading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`. Saving a draft over an active template keeps the active version served and stores the edit beside it (column `draft`); `publish` makes it the served version, `discardDraft` / `discardDraftSystem` throws it away.\n\nText an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation.\n\nHow a collection is edited follows from `contentFormat`: `plain` gives a text area, `rich` a small WYSIWYG (bold, italic, headings, lists, links), `markdown` a text area that stores markdown text (same insertable chips as `plain`). All three offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning).\n\nA collection is tenant-wide by default. With `ownership: \"user\"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side.\n\n`validate` dry-runs the write pipeline for a draft (sanitizer, layout rules, placeholders) and reports what the template uses and misses. `export-bundle` / `import-bundle` (and `import-bundle-system`) move one template with all locales and resource files between tenants or environments; `copy-locale` starts a translation from an existing locale. Layouts are structured: a mail or PDF layout is `data-header` / `data-content` / `data-signature` / `data-footer` regions, and mjml layout source is system-only.\n\n`preview` renders a draft (or the stored template) with sample values taken from the `example` of each declared variable, through the same gates and the same mail renderer as a real send, and returns subject, html, `displayHtml` (the html with cid images as data URIs for an editor), text, attachments (inline images and files) and `checks` (images resolved, plain text present, size under 10 MiB, required placeholders used); nothing is saved or sent. `send-test` mails that rendering to the calling user's own address only, subject prefixed with `[TEST]`, at most 10 per user and hour; it needs `delivery`, `channel-email` and `renderer-mail-html` to be mounted.\n\nImages used by a template (`<img data-resource=\"logo\">`) are uploaded with `resourceUpload`, which re-encodes them, stores a file and links it under the key; `resourceRemove` unlinks it. `linkedResources` is written only through these two handlers. With `purpose: \"attachment\"` and a `fileName`, `resourceUpload` stores a PDF, PNG or JPEG as a file attachment of a mail template (original bytes, at most 10) that the mail renderer attaches after the inline images. `resourceLinkPdf` instead links a `document-pdf` template under a key: every mail sent from the template then carries that PDF, rendered at send time with the mail's own variables and locale, under a file name pattern such as `invoice-{{number}}.pdf`; files and linked PDFs share the limit of 10.\n\nReplaces the former `text-content` feature; its blocks now live here as kind `text-block`.",
+      "description": "Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail`, `mail-layout`, `document-pdf`, `pdf-layout`, `ai-prompt`, `text-block`, `snippet`, `image-snapshot`).\n\nReading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`. Saving a draft over an active template keeps the active version served and stores the edit beside it (column `draft`); `publish` makes it the served version, `discardDraft` / `discardDraftSystem` throws it away.\n\nEditing templates is for SystemAdmin only. A TenantAdmin edits only the templates the app unlocks at the mount site, `createTemplateResolverFeature({ tenantEditable: [{ kind: \"mail\", slug: \"status-update\", access: { roles: [\"TenantAdmin\"] } }] })`, and every write handler enforces that on the server (override, draft, publish, archive, reset, copy-locale, import, resources, `set`). Each entry carries the `access` roles allowed to edit it, because a bundled feature cannot know the host's roles. Reading and delivery do not depend on it: a tenant override that exists is served. A collection mounted without `access` is SystemAdmin only.\n\nText an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation.\n\nHow a collection is edited follows from `contentFormat`: `plain` gives a text area, `rich` a small WYSIWYG (bold, italic, headings, lists, links), `markdown` a text area that stores markdown text (same insertable chips as `plain`). All three offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning).\n\nA collection is tenant-wide by default. With `ownership: \"user\"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side.\n\n`validate` dry-runs the write pipeline for a draft (sanitizer, layout rules, placeholders) and reports what the template uses and misses. `export-bundle` / `import-bundle` (and `import-bundle-system`) move one template with all locales and resource files between tenants or environments; `copy-locale` starts a translation from an existing locale. Layouts are structured: a mail or PDF layout is `data-header` / `data-content` / `data-signature` / `data-footer` regions, and mjml layout source is system-only.\n\n`preview` renders a draft (or the stored template) with sample values taken from the `example` of each declared variable, through the same gates and the same mail renderer as a real send, and returns subject, html, `displayHtml` (the html with cid images as data URIs for an editor), text, attachments (inline images and files) and `checks` (images resolved, plain text present, size under 10 MiB, required placeholders used); nothing is saved or sent. `send-test` mails that rendering to the calling user's own address only, subject prefixed with `[TEST]`, at most 10 per user and hour; it needs `delivery`, `channel-email` and `renderer-mail-html` to be mounted. `send-test-status` tells an editor beforehand whether that send can work for the caller (`canSend`, else `reason` `no_channel` or `no_address`), never returning the address.\n\nImages used by a template (`<img data-resource=\"logo\">`) are uploaded with `resourceUpload`, which re-encodes them, stores a file and links it under the key; `resourceRemove` unlinks it. `linkedResources` is written only through these two handlers. With `purpose: \"attachment\"` and a `fileName`, `resourceUpload` stores a PDF, PNG or JPEG as a file attachment of a mail template (original bytes, at most 10) that the mail renderer attaches after the inline images. `resourceLinkPdf` instead links a `document-pdf` template under a key: every mail sent from the template then carries that PDF, rendered at send time with the mail's own variables and locale, under a file name pattern such as `invoice-{{number}}.pdf`; files and linked PDFs share the limit of 10.\n\nReplaces the former `text-content` feature; its blocks now live here as kind `text-block`.",
       "toggleableDefault": null,
       "requires": [],
       "optionalRequires": [],

package/samples/recipes/delivery-notifications/README.md

@@ -8,7 +8,7 @@ Shows how a feature sends notifications to multiple channels (InApp + Email + Pu
 
 **Mail text is stored data:** The boot seed (`seedNotificationTemplates`) writes the declared `template` and `meta` into the template store as system templates. The email channel renders them with `renderer-mail-html`. A notification routed to email without `template` and `meta` fails its delivery.
 
-**Tenant override:** A tenant admin overrides the text through the template-resolver handlers (`upsertTenant`, then `publish`). The next mail for that tenant uses the override; the system text stays for everyone else.
+**Tenant override:** Only a SystemAdmin edits templates unless the app unlocks them. The app lists the mail in `createTemplateResolverFeature({ tenantEditable: [{ kind: "mail", slug, access: { roles: ["TenantAdmin"] } }] })`; then a tenant admin overrides the text through the template-resolver handlers (`upsertTenant`, then `publish`) and every other template is refused with 403. The next mail for that tenant uses the override; the system text stays for everyone else.
 
 **Sending:** The write handler calls `ctx.notify(type, { to, data })`. The `data` keys are the template variables; sending fails loudly when a required variable is missing.
 

package/samples/recipes/embedded/README.md

@@ -19,6 +19,14 @@ object and an embedded list rendered by a declarative `entityEdit` screen.
   `createEmbeddedListField`; its renderer receives `embeddedListCells`, so no
   custom screen component is required.
 
+- **Derived head totals** (`src/screens/invoice-receive.screen.ts`): an
+  `actionForm` declares `derive` so net, VAT, and gross follow the lines
+  (`listSum`), or follow a typed net and VAT rate while the list is empty
+  (`whenEmpty`, `percent`). The renderer shows them read-only and live; the
+  handler wraps its schema with `withFormDerivations(schema, screen)`
+  (`src/handlers/invoice-receive.write.ts`), so totals sent by the client are
+  replaced on the server.
+
 ## When to reach for it
 
 Use an embedded field or list when the nested data is created, changed, and

package/samples/recipes/embedded/src/feature.ts

@@ -15,6 +15,9 @@
 //             on its `lines` sub-fields (Issue #1835), plus a declarative
 //             entityEdit screen that renders the list end-to-end via
 //             EmbeddedListField, no custom-screen code required
+//   invoice-receive — actionForm whose net/VAT/gross head fields are derived
+//             from the lines (`derive`); the handler recomputes them with
+//             `withFormDerivations`, so client-sent totals are never trusted
 
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { contactEntity } from "./entities/contact";
@@ -22,6 +25,8 @@ import { invoiceEntity } from "./entities/invoice";
 import { productEntity } from "./entities/product";
 import { contactCreate } from "./handlers/contact-create.write";
 import { contactDetail } from "./handlers/contact-detail.query";
+import { invoiceReceive } from "./handlers/invoice-receive.write";
+import { invoiceReceiveScreen } from "./screens/invoice-receive.screen";
 
 export { contactEntity } from "./entities/contact";
 export { invoiceEntity } from "./entities/invoice";
@@ -43,6 +48,7 @@ export const embeddedFeature = defineFeature("contacts", (r) => {
 
   r.writeHandler(contactCreate);
   r.queryHandler(contactDetail);
+  r.writeHandler(invoiceReceive);
 
   r.crud("product", productEntity, { write: adminWrite, read: openRead });
   r.crud("invoice", invoiceEntity, { write: adminWrite, read: openRead });
@@ -55,4 +61,6 @@ export const embeddedFeature = defineFeature("contacts", (r) => {
       sections: [{ columns: 1, fields: ["customer", "lines"] }],
     },
   });
+
+  r.screen(invoiceReceiveScreen);
 });